Overview

Controllers are how your code receives the SDK’s events and, when needed, overrides default behavior. Implement only the ones you need.

Defaults

Controller	Not overridden	Overridden
`onStatus`	You don’t receive the final status.	Receives the transaction status (`status`, `substatus`, `message`) once the transaction reaches a final state. On Web it also receives a few retryable outcomes that keep the form mounted. See `onStatus`.
`showView` (iOS, Android)	SDK presents forms and action views (e.g. 3DS) full-screen.	SDK hands you the view and a `TransactionProcess`; embed it and call `process.onSubmit()`.
`showLoading`	SDK shows its own loader.	SDK suppresses its loader and emits `isLoading: true/false`.
`createPayment`	SDK creates the payment after tokenization.	SDK delivers the One-Time Token; you create the payment from your backend and resolve.
`onInstallmentSelected`	Nothing happens — the selection still travels with the payment.	Receives the installment option the buyer picks in the card form, and `null` when that selection stops being valid.
`onShippingAddressChanged`	The wallet sheet keeps its totals; no shipping options or errors are applied.	Receives each shipping-address selection and returns the totals, shipping options or error the sheet must display.
`onChange` (Web)	Nothing happens.	Receives `{ form: { isValid } }` when the transaction starts and whenever the validity of the form the SDK rendered changes.

Implement onStatus in every integration. The others are optional. Web has no showView: the SDK renders the form inside your elementSelector. To submit it from your own button, set showPayButton: false and call transaction.submit().

How to wire controllers

Web. Each event is a plain function set on the transaction config. onStatus, showLoading, createPayment and onChange are top-level fields. onInstallmentSelected goes inside card (card: { onInstallmentSelected }) and onShippingAddressChanged inside externalButtons (externalButtons: { onShippingAddressChanged }).
iOS, Android. Implement TransactionController on the object that should react to events (your view model, activity, or a dedicated class) and pass it through the controller field of TransactionConfig. Each event maps to a method on that object. showView is available on mobile only.

Threading

On iOS and Android, every controller method is invoked on the main thread. You can update UI directly from inside it. Move any blocking work (e.g. backend calls inside createPayment) off the main thread yourself.

Per-controller pages

onStatus. Required. The final outcome of the transaction.
Take over the SDK: showView (iOS, Android), showLoading, createPayment. Override one and the SDK stops doing that step itself.
Listen to events: onInstallmentSelected, onShippingAddressChanged, onChange (Web). Informational; the SDK behaves the same with or without them.

Start here

Guides

Listen and take over

API reference

Upgrade from older SDKs

Defaults

How to wire controllers

Threading

Per-controller pages

​Defaults

​How to wire controllers

​Threading

​Per-controller pages

Defaults

How to wire controllers

Threading

Per-controller pages