Events

Components surface callbacks from shopper interaction and validation. You attach closures on configuration types in PXPCheckoutSDK so your app can run business rules and refresh the UI while the SDK handles PCI scope, tokenisation, optional 3DS, and transport.

Callbacks enable you to:

• Validate business rules before payments proceed.
• Display custom error, failure, or success messages.
• Tailor the interface to match your app.
• Integrate with fraud tools or your own customer systems.
• Control how shoppers experience both successful and failed transactions.
• Drive loading states, token lists, saved-card flows, and 3DS where you enable it.

All events are optional and can be mixed and matched based on your business needs.

Use the matrices below to see which pre-built or standalone surface supports each callback; expand a cell for scope. Session-wide hooks live on CheckoutConfig (onGetShopper, onGetShippingAddress, analyticsEvent — see Analytics). Pay lifecycle hooks live on CardSubmitComponentConfig, usually nested under NewCardComponentConfig.submit or ClickOnceComponentConfig.cardSubmitComponentConfig (About configuration, Card submit).

Builds the primary action control for Click Once standalone flows. Also supported on pre-built Click Once when shown in the matrix.

Use this to match your app’s button styling for one-tap checkout.

(ClickOnceButtonBuilderElements) -> AnyView (see SDK types and Click Once).

Runs when a billing or card field loses focus (FieldComponentConfig and SecuredFieldComponentConfig subclasses).

Use this to hide inline help or run your own validation pass after the shopper leaves the field.

() -> Void — no payload; read values from your own state if needed.

CardNumberComponentConfig(
    label: "Card number",
    onBlur: { /* update UI */ }
)

Runs on the card number field when digits don't match a known brand pattern.

Use this to show generic card art or guidance for unknown BIN ranges.

(CardBrandDetectionEvent) -> Void

Runs when the card number field recognises a scheme.

Use this to swap card art, show accepted-brand messaging, or log analytics.

(CardBrandDetectionEvent) -> Void — same payload shape as onCardBrandCannotRecognised.

Runs when the shopper edits a billing or card field (not the pay button state).

Use this to sync custom labels, enable dependent fields, or debounce your own checks.

() -> Void — no payload for these configs.

Runs when CardSubmitComponent coarse state changes (idle, loading, success, error).

Use this to drive a global spinner or disable navigation while submit is in flight.

(ComponentState) -> Void

Runs when the shopper activates the submit control, before deeper validation.

Use this to log intent, play haptics, or guard double submission at the very start of the tap.

() -> Void on CardSubmitComponentConfig.

Runs when a device-data collection phase finishes during submit.

Use this to clear intermediate UI tied to collection.

(Any) -> Void — treat the argument as opaque unless your SDK version documents it.

Runs when a device-data collection phase starts during submit.

• Show “preparing secure check” style messaging.

(Any) -> Void

Runs after field validation passes; return whether submit may continue.

Use this to re-check basket price, inventory, or session with your backend before tokenisation.

() async -> Bool — return false to block submit.

Runs when deleting a saved token from the vault fails (CardOnFileComponentConfig).

Use this to show an error and keep the list consistent.

(DeleteCardTokenResponseFailed) -> Void

Runs when a saved token was removed successfully.

Use this to refresh your local list and analytics.

(DeleteCardTokenResponseSuccess) -> Void

Runs when a billing or card field receives focus.

Use this to show inline help or scroll the field into view.

() -> Void

Async hook on CardSubmitComponentConfig when the flow needs a fingerprint string.

Use this to return device or session data your processor expects.

() async -> String

Runs when the shopper uses the Click Once one-tap affordance (standalone or pre-built, per matrix).

Use this to start your server-side path for that flow or log funnel events.

See ClickOnceStandaloneComponentConfig in Click Once.

Runs after the 3DS authentication step completes (success or failure path), on CardSubmitComponentConfig.

Use this to log authentication outcomes or adjust UI before authorisation continues.

(AuthenticationResult) -> Void — cast to FailedAuthenticationResult or ExceptionAuthenticationResult on failure paths; see 3DS.

Runs after the gateway has finished processing the payment (authorised, captured, refused, or failed).

Use this to navigate, show receipts, or reconcile orders.

(BaseSubmitResult) -> Void

Downcast result — common types include AuthorisedSubmitResult, CapturedSubmitResult, RefusedSubmitResult, FailedSubmitResult, and MerchantSubmitResult depending on intent and response.

submitConfig.onPostAuthorisation = { result in
    if let success = result as? AuthorisedSubmitResult {
        print("transaction=\(success.fundingData.transactionId ?? "")")
    } else if let refused = result as? RefusedSubmitResult {
        print("refused: \(refused.state ?? "")")
    } else if let failed = result as? FailedSubmitResult {
        print("failed: \(failed.errorCode ?? "") \(failed.errorReason ?? "")")
    }
}

Runs after the 3DS pre-initiate call returns.

Use this to inspect coarse stateData or handle FailedAuthenticationResult.

(AuthenticationResult) -> Void — see 3DS.

Runs after tokenisation completes. Appears on NewCardComponentConfig and on CardSubmitComponentConfig when nested as submit (see Supported events).

Use this to store gatewayTokenId for subscriptions or card on file.

(CardTokenizationResult) -> Void — cast to CardTokenizationResultSuccess or CardTokenizationResultFailed.

submitConfig.onPostTokenisation = { result in
    if let ok = result as? CardTokenizationResultSuccess {
        print("token=\(ok.gatewayTokenId)")
    } else if let fail = result as? CardTokenizationResultFailed {
        print("token failed: \(fail.errorCode) \(fail.errorReason ?? "")")
    }
}

Async hook before 3DS authentication runs; return initiate payload or nil to abort.

Use this to supply merchant country, legal name, challenge window, shopper contact, and optional ThreeDSRecurring for recurring setups.

() async -> InitiateIntegratedAuthenticationData? — see 3DS.

Runs before the authorisation request is sent. Required for the authorisation step to complete as expected.

Use this to return TransactionInitiationData (PSD2 exemptions, risk payloads) or nil to stop.

(PreAuthorizationData?) async -> TransactionInitiationData?

PreAuthorizationData in this build exposes gatewayTokenId and schemeTokenId where applicable.

submitConfig.onPreAuthorisation = { preAuth in
    // This is an async closure - you can use await here if needed
    // await someAsyncOperation()
    _ = preAuth?.gatewayTokenId
    return TransactionInitiationData()
}

Runs before the SDK deletes a saved token; return whether to proceed.

Use this to confirm with your server or show a final confirmation sheet.

(BaseCardToken) async -> Bool

Async hook before 3DS pre-initiate; return data or nil to skip 3DS for that attempt.

Use this to supply providerId, requestor indicator, and timeouts.

() async -> PreInitiateIntegratedAuthenticationData? — pair with onPreAuthentication per 3DS and Non-3DS.

Runs when the saved-card list is about to render; return mappings for display.

Use this to filter or reorder tokens for the current session (CardOnFileComponentConfig; also Click Once retrieve flows per matrix).

(RetrieveCardTokensResponseSuccess) -> [CardTokenMapping]

Runs when the SDK offers a soft-decline retry path.

Use this to decide whether to retry with adjusted data.

(BaseSubmitResult) -> SoftDeclineRetryResult — see Card submit.

Runs immediately before tokenisation; return whether to continue.

Use this to gate on consent when you don't use CardConsentComponent, or block when fraud checks fail.

() -> Bool — return false to cancel.

Runs when loading saved tokens fails (card on file or Click Once, per matrix).

Use this to show retry UI or fall back to new-card entry.

(RetrieveCardTokensResponseFailed) -> Void on card on file; Click Once uses ClickOnceRetrieveTokensError — see Click Once.

Runs when saved tokens were loaded successfully.

Use this to bind your model to gatewayTokens / schemeTokens.

(RetrieveCardTokensResponseSuccess) -> Void on card on file; Click Once uses ClickOnceRetrieveTokensSuccess — see Click Once.

Runs when the shopper picks a saved token in card on file.

Use this to highlight the row and pass the token id to submit.

(BaseCardToken) -> Void — cast to GatewayToken or SchemeToken as needed.

cofConfig.onSelectToken = { token in
    if let gateway = token as? GatewayToken {
        print("Selected: \(gateway.gatewayTokenId)")
    }
}

Runs after field validation passes and before tokenisation on CardSubmitComponentConfig.

Use this to show a full-screen or inline loading state for the pay journey.

() -> Void

Runs when the SDK reports a failure during submit (validation, vault, network, 3DS runtime, and similar).

Use this to clear loading UI and map errorCode to shopper-safe copy.

(BaseSdkException) -> Void — use errorCode and errorMessage.

submitConfig.onSubmitError = { error in
    switch error.errorCode {
    case "SDK0503", "SDK0505":
        showAuthenticationRetryUI()
    default:
        showGenericPaymentError(error.errorMessage)
    }
}

Runs when updating token metadata on the vault fails.

Use this to show an error toast and revert UI.

(UpdateCardTokenResponseFailed) -> Void

Runs when a saved token was updated successfully.

Use this to refresh labels (for example new expiry).

(UpdateCardTokenResponseSuccess) -> Void

Aggregates linked field validation for submit (CardSubmitComponentConfig), or appears on NewCardComponentConfig for container-level results — prefer submit and per-field callbacks for most UX (New card).

Use this to enable or disable the pay button from one snapshot.

([ValidationResult]) -> Void

let newCardConfig = NewCardComponentConfig(
    fields: fields,
    submit: submit,
    onValidation: { results in
        let ok = results.allSatisfy(\.valid)
        updatePayButtonEnabled(ok)
    }
)

Runs when a field fails validation for that field’s config.

Use this to show inline errors from ValidationResult.errors.

([ValidationResult]) -> Void

Runs when a field passes validation for that field’s config.

Use this to clear error state for that field.

([ValidationResult]) -> Void

CountrySelectionComponentConfig(
    label: "Country",
    onValidationFailed: { results in
        for result in results where !result.valid {
            result.errors?.values.forEach { print($0.code, $0.message) }
        }
    }
)

Runs for SDK validation-style errors on card-on-file or Click Once (for example CVC format), as BaseSdkException.

Use this to map errorCode / errorMessage next to the saved-card entry UI.

(BaseSdkException) -> Void

Runs when the shopper pastes into a secured field (PAN, expiry, CVC).

Use this to track paste-assisted entry or adjust formatting hints.

() -> Void on SecuredFieldComponentConfig subclasses.

Builds each token row in Click Once token selection UI.

Use this to render scheme icons and masked PAN in SwiftUI.

See ClickOnceStandaloneComponentConfig in Click Once.

Builds each saved card row for card on file.

Use this to customise list layout beyond default styling.

(CardTokenBuilderElements) -> AnyView

Produces the subtitle or label string for a saved token row.

Use this to show Scheme •••• 1234 style text.

(BaseCardToken) -> String

cofConfig.tokenLabelBuilder = { token in
    let last4 = String(token.maskedPrimaryAccountNumber.suffix(4))
    return "\(token.cardScheme.rawValue) •••• \(last4)"
}

Optional instance hook on FieldComponent (not on FieldComponentConfig). The SDK may set it internally.

Use this to react to imperative validation triggers if you attach to the component after creation.

Prefer onValidationPassed / onValidationFailed on configs for normal flows.