onStatus is invoked when the transaction reaches its final state. It is the only way to know how the transaction ended.
Behavior
This controller has no default behavior. If you don’t implement it, you won’t receive the final status. On Web,transaction() also prints a console warning when the config has no onStatus function.
When implemented, the SDK delivers the status to your handler after tokenization, payment creation (or merchant-side payment creation via createPayment), 3DS, and status resolution have completed.
Some deliveries are not final: on iOS and Android an asynchronous payment can report PENDING first and its final status later, and closing a payment screen reports what the shopper did, not how the payment ended. See Deliveries that are not final.
Signature
- Web
- iOS
- Android
- React Native
Wire it as a field on the config.
result has the same shape on payment and enrollment flows:A status this SDK version does not know is not passed through. It arrives as
INTERNAL_ERROR with message.code UNSUPPORTED_STATUS and message.reason set to unsupported status: <value>.Status for the shape of the payload, the message field, and the SDK-emitted values (INTERNAL_ERROR, USER_CANCEL).
Confirm on your server
onStatus runs on the user’s device, so it can be missed (the app is killed, the network drops, the user closes the page mid-flow) or manipulated (anything running on the client can be tampered with). A SUCCEEDED delivered to your handler is not proof that money moved.
Before shipping goods, granting access, or marking an order as paid, confirm the outcome on your backend:
- Webhooks (recommended). Configure webhooks so Yuno notifies your backend of every payment status change, independently of what happens on the client. Verify the notification signature before trusting it.
- Query the API. Have your backend call Retrieve Payment by ID (or by
merchant_order_id) and read the status from the response.
onStatus as the trigger to update the screen, and the server-side confirmation as the trigger to fulfill.
Deliveries that are not final
Asynchronous payments on mobile
On iOS and Android,onStatus can run more than once for one transaction. Asynchronous methods (PIX, boleto, OXXO, bank transfers and similar) report status PENDING as soon as the payment exists and the shopper has the payment instructions, with the backend substatus when there is one. The final status arrives in a later call, once Yuno confirms the payment.
Treat PENDING as not final: keep your screen in a waiting state and confirm the outcome on your server. React Native apps receive the same deliveries as the native SDK of the platform.
When the shopper closes a payment screen on mobile
On iOS and Android, whatonStatus receives depends on the screen the shopper closes. In every case the payment is not cancelled on the backend.
Web deliveries that keep the form mounted
On Web, these deliveries are not final. The form stays mounted after them, so the shopper can try again:
Without
createPayment, a form mounted by start() has no in-place retry: the decline is final and reaches onStatus. On the payment methods list and with secure fields the SDK retries in place and does not call onStatus for the declined attempt.
On Web, USER_CANCEL also arrives when you call transaction.unmount() while a form is mounted and the transaction has not delivered a status yet, unless a payment is in flight. Unmount after onStatus has fired, or treat that delivery as the shopper leaving the payment.
Web error codes
On Web, anINTERNAL_ERROR with message.source 'sdk' can carry these values in message.code:
With
message.source 'backend', message.code is the backend error code, or the HTTP status when the response body has none. Branch on message.code for the cases you handle and treat the rest as a generic failure.
Threading
On iOS and Android,onStatus is invoked on the main thread. You can update UI directly from inside this handler. On React Native it runs on the JavaScript thread.
Related
Status. Values and substatus information.- Transactions. How a payment flows through Yuno.
- Payment status values. Status and substatus reference.
showStatusScreen. Flag to enable or disable the SDK’s built-in result screen.