onStatus se invoca cuando la transacción llega a su estado final. Es la única forma de saber cómo terminó la transacción.
Comportamiento
Este controlador no tiene un comportamiento predeterminado. Si no lo implementas, no recibirás el estado final. En Web,transaction() también imprime una advertencia en la consola cuando la configuración no tiene una función onStatus.
Cuando lo implementas, el SDK entrega el estado a tu handler después de que se completan la tokenización, la creación del pago (o la creación del pago del lado del comercio mediante createPayment), 3DS y la resolución del estado.
Algunas entregas no son finales: en iOS y Android un pago asíncrono puede informar PENDING primero y su estado final después, y cerrar una pantalla de pago informa lo que hizo el comprador, no cómo terminó el pago. Consulta Entregas que no son finales.
Firma
- Web
- iOS
- Android
- React Native
Conéctalo como un campo de la configuración.
result tiene la misma forma en los flujos de pago y de inscripción:Un estado que esta versión del SDK no conoce no se transmite tal cual. Llega como
INTERNAL_ERROR con message.code UNSUPPORTED_STATUS y message.reason con el valor unsupported status: <value>.Status para ver la forma del payload, el campo message y los valores que emite el SDK (INTERNAL_ERROR, USER_CANCEL).
Confirma en tu servidor
onStatus se ejecuta en el dispositivo del usuario, por lo que puede perderse (la app se cierra, se cae la red, el usuario cierra la página a mitad del flujo) o manipularse (cualquier cosa que se ejecute en el cliente puede alterarse). Un SUCCEEDED entregado a tu handler no es prueba de que el dinero se haya movido.
Antes de enviar productos, otorgar acceso o marcar un pedido como pagado, confirma el resultado en tu backend:
- Webhooks (recomendado). Configura webhooks para que Yuno notifique a tu backend cada cambio de estado del pago, independientemente de lo que ocurra en el cliente. Verifica la firma de la notificación antes de confiar en ella.
- Consulta la API. Haz que tu backend llame a Retrieve Payment by ID (o por
merchant_order_id) y lea el estado de la respuesta.
onStatus como el disparador para actualizar la pantalla, y la confirmación del lado del servidor como el disparador para entregar el pedido.
Entregas que no son finales
Pagos asíncronos en móvil
En iOS y Android,onStatus puede ejecutarse más de una vez para una misma transacción. Los métodos asíncronos (PIX, boleto, OXXO, transferencias bancarias y similares) informan status PENDING apenas existe el pago y el comprador tiene las instrucciones de pago, con el substatus del backend cuando hay uno. El estado final llega en una llamada posterior, una vez que Yuno confirma el pago.
Trata PENDING como no final: mantén tu pantalla en estado de espera y confirma el resultado en tu servidor. Las apps de React Native reciben las mismas entregas que el SDK nativo de la plataforma.
Cuando el comprador cierra una pantalla de pago en móvil
En iOS y Android, lo que recibeonStatus depende de la pantalla que cierre el comprador. En todos los casos el pago no se cancela en el backend.
Entregas en Web que mantienen el formulario montado
En Web, estas entregas no son finales. El formulario sigue montado después de ellas, para que el comprador pueda intentarlo de nuevo:
Sin
createPayment, un formulario montado con start() no tiene reintento en el lugar: el rechazo es final y llega a onStatus. En la lista de métodos de pago y con secure fields, el SDK reintenta en el lugar y no llama a onStatus para el intento rechazado.
En Web, USER_CANCEL también llega cuando llamas a transaction.unmount() mientras hay un formulario montado y la transacción aún no ha entregado un estado, a menos que haya un pago en curso. Desmonta después de que onStatus se haya disparado, o trata esa entrega como que el comprador abandonó el pago.
Códigos de error en Web
En Web, unINTERNAL_ERROR con message.source 'sdk' puede traer estos valores en message.code:
Con
message.source 'backend', message.code es el código de error del backend, o el estado HTTP cuando el cuerpo de la respuesta no tiene uno. Ramifica según message.code para los casos que manejas y trata el resto como una falla genérica.
Hilos de ejecución
En iOS y Android,onStatus se invoca en el hilo principal. Puedes actualizar la interfaz directamente desde este handler. En React Native se ejecuta en el hilo de JavaScript.
Relacionado
Status. Valores e información de subestados.- Transactions. Cómo fluye un pago por Yuno.
- Payment status values. Referencia de estados y subestados.
showStatusScreen. Indicador para habilitar o deshabilitar la pantalla de resultado integrada del SDK.