Saltar al contenido principal
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

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>.
Consulta 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 es una señal del lado del cliente. Úsalo para controlar tu interfaz, nunca como la fuente de verdad para entregar el pedido.
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.
Trata 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 recibe onStatus 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, un INTERNAL_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.