Skip to main content
All systems operationalChangelogv1
Log in
SDKs

SDK events

Observe DEUNA SDK lifecycle events across Web, iOS, Android, and React Native without treating analytics events as payment state.

Last updated October 16, 2026
On this page

SDK events describe what the customer and widget are doing. Use them for analytics, diagnostics, and interface changes. Use typed success and error callbacks for the immediate UI, and verify the final order state on your backend before fulfillment.

Event lifecycle#

01 · client
Open the experience
Payment Widget, Elements, Voucher, or Next Action starts.
02 · SDK
Dispatch lifecycle events
The SDK forwards supported names and their raw, experience-specific payloads.
03 · interface
React locally
Update loading, validation, and analytics without exposing payment data.
04 · backend
Confirm the outcome
Retrieve the order or consume a verified webhook before fulfillment.
Sequence diagram
1Customer2Merchant app3DEUNA SDK4Merchant backendOpens paymentInitialize experiencecheckoutStarted /paymentMethodsStartedSelects and submitspaymentMethodsSelected /paymentProcessingonSuccess or onErrorVerify authoritativeorder stateConfirm fulfillment decision
Merchant or customerDEUNA

Subscribe by platform#

await DeunaSDK.initPaymentWidget({
  orderToken,
  callbacks: {
    onEventDispatch: (event, payload) => {
      analytics.track(`deuna.${event}`, sanitize(payload));
    },
  },
});

The Web and React Native callbacks expose the event name as a string. Native SDKs expose typed CheckoutEvent or ElementsEvent values. Keep a default branch so a newly released event does not break your analytics adapter.

Stable integration signals#

Prefer dedicated callbacks when one exists. They provide a smaller, typed contract than the raw event stream.

SignalWebiOSAndroidReact NativeRecommended use
onSuccessYesYesYesYesClose or replace the experience, then verify final state.
onErrorYesYesYesYesRender a retry or recovery path from the documented error envelope.
onClosedYesYesYesYesRestore the merchant UI after customer or SDK closure.
onCardBinDetectedPayment + ElementsPayment + ElementsPayment + ElementsPayment + ElementsRecalculate card-specific offers or styling.
onInstallmentSelectedPayment + ElementsPayment + ElementsPayment + ElementsPayment + ElementsRecord the selected plan identifier without storing card data.
onPaymentProcessingPayment + VoucherPaymentPaymentPayment + VoucherDisable duplicate submit actions.
onResizeYesEmbedded lifecycleEmbedded lifecycleYesKeep an embedded container aligned with content.

See SDK responses for payloads and error handling.

High-value lifecycle events#

EventMeaningExperience notes
checkoutStartedThe checkout experience started loading or initialized.Present in Web and native checkout streams.
paymentMethodsStartedThe payment-method step became active.Native and React Native checkout streams.
paymentMethodsSelectedThe customer selected a payment method.Web and native checkout streams.
onBinDetectedThe card BIN was detected.Prefer onCardBinDetected when available.
onInstallmentSelectedThe customer chose an installment option.Prefer the dedicated typed callback.
paymentProcessingSubmission is being processed.Disable duplicate actions; do not infer approval.
purchaseThe widget reported a successful purchase interaction.Use onSuccess, then verify the order on the backend.
purchaseErrorThe purchase interaction failed.Use onError for the normalized error envelope.
purchaseRejectedThe native checkout reported a rejection.Available in native and React Native streams, not the current Web enum.
vaultSaveSuccessElements reported a saved credential.Web and native Elements flows.
vaultSaveErrorElements could not save the credential.Treat payload as experience-specific.
linkCloseThe hosted experience requested closure.The SDK also invokes onClosed.

Current event catalogs#

These names are the public enums in the maintained SDK source. Payload objects are deliberately raw because their fields vary by experience and release; only depend on a payload field when a dedicated callback documents it.

Web SDK18 event names

checkoutStarted, paymentMethodsEntered, onBinDetected, purchase, paymentProcessing, loginStarted, paymentMethodsSelected, loginOtpStarted, purchaseError, onInstallmentSelected, linkClose, checkoutReady, vaultSaveSuccess, vaultSaveError, checkoutFailed, openExternalPopup, closeExternalPopup, errorApmMissingReference.

React Native · checkoutCurrent CheckoutEventType

custom, purchase, purchaseError, linkClose, linkFailed, purchaseRejected, paymentProcessing, paymentMethodsAddCard, paymentMethodsCardExpirationDateInitiated, paymentMethodsCardNameEntered, apmSuccess, apmSuccessful, changeAddress, changeCart, paymentClick, apmClickRedirect, paymentMethodsCardNumberInitiated, paymentMethodsCardNumberEntered, paymentMethodsEntered, checkoutStarted, linkStarted, paymentMethodsStarted, paymentMethodsSelected, adBlock, paymentMethods3dsInitiated, pointsToWinStarted, paymentMethodsCardSecurityCodeInitiated, paymentMethodsCardSecurityCodeEntered, paymentMethodsCardExpirationDateEntered, paymentMethodsCardNameInitiated, paymentMethodsNotAvailable, paymentMethodsShowMore, paymentMethodsShowMyCards, benefitsStarted, donationsStarted, donationsUsed, onBinDetected, onInstallmentSelected, onDownloadVoucher, errorApmMissingReference.

React Native · ElementsCurrent ElementsEventType

vaultClosed, vaultProcessing, vaultSaveClick, vaultStarted, vaultFailed, cardSuccessfullyCreated, changeAddress, changeCart, vaultSaveError, vaultSaveSuccess, vaultClickRedirect3DS, cardCreationError, paymentMethodsCardIdentityNumberInitiated, paymentMethodsCardIdentityNumberEntered, paymentMethodsCardNameInitiated, paymentMethodsCardNameEntered, paymentMethodsCardSecurityCodeInitiated, paymentMethodsCardSecurityCodeEntered, paymentMethodsCardExpirationDateEntered, paymentMethodsCardExpirationDateInitiated, paymentMethodsCardNumberEntered, paymentMethodsCardNumberInitiated, paymentMethodsEntered, paymentMethodsStarted.

iOS and Android · checkoutTyped CheckoutEvent catalogs

The native catalogs include the checkout, login, billing, shipping, user-information, APM, coupon, donation, card-entry, installment, processing, purchase, rejection, and failure events exposed by each platform. Android additionally publishes apmFailed, couponStarted, linkCriticalError, and userInfoPhoneInitiated; iOS publishes custom. Code against the enum shipped with your installed SDK rather than assuming the two native catalogs are byte-for-byte identical.

iOS and Android · ElementsTyped ElementsEvent catalogs

Both native SDKs publish card-entry, BIN, installment, checkout, vault lifecycle, and credential-save events. Their current catalogs include paymentMethodSplitPayments, vaultClickRedirect3DS, vaultProcessing, vaultSaveClick, vaultSaveError, and vaultSaveSuccess.

Analytics and privacy#

  • Allow-list event names before forwarding them to a third-party analytics destination.
  • Remove order, customer, payment-method, and provider metadata unless your data contract explicitly permits it.
  • Never record PAN, security code, wallet tokens, access tokens, or the complete raw payload.
  • Include your app version, SDK version, environment, and a merchant-owned correlation ID for diagnostics.
  • Treat unknown event names as forward-compatible signals, not fatal errors.

Public source contracts#

The catalogs above are checked against the maintained public enums rather than copied from a historical event list:

SDK responsesTyped callbacks, errors, and payload boundaries.Payment WidgetDetailed Web Payment Widget integration.WebhooksAuthoritative server-to-server state changes.