Flujo de compra de 3DS
Maneje la autenticación pendiente, presente la siguiente acción y confirme el estado del pago final.
En esta página
Envía el pago con tarjeta una sola vez, presenta cualquier siguiente acción 3DS devuelta y verifica el resultado del pago en tu backend. La experiencia de autenticación puede recopilar señales del navegador, finalizar sin un desafío o pedir al cliente que se autentique con su banco.
La autenticación puede fallar o interrumpirse en cualquier etapa. El diagrama muestra el recorrido habitual; el estado actual del pago determina si debes esperar, completar la entrega u ofrecer una recuperación.
Responsabilidades de tu integración#
Tu backend crea el pago y verifica su resultado. Tu checkout presenta la acción devuelta y conserva el contexto del pedido original. DEUNA coordina las comprobaciones del navegador, la autenticación y cualquier autorización pendiente con el proveedor conectado; el emisor controla el desafío y la decisión de autenticación.
No construyas tu propia secuencia de llamadas de autenticación al proveedor ni supongas que cada paso del diagrama requiere una solicitud API independiente del comercio. Usa la acción devuelta mediante la integración compatible con tu conexión.
1. Crea el pago#
Utilice cualquiera de los patrones de pago con tarjeta admitidos:
- Crear un pedido con Crear orden, luego paga con Crear pago.
- Utilice la solicitud única Crear pago fluya cuando se ajuste a su integración.
Envíe información completa del comprador, facturación, pedido y dispositivo. Estas señales ayudan al emisor a decidir si la autenticación puede realizarse sin fricciones.
2. Inspeccione la respuesta de pago.#
Una respuesta 3DS pendiente puede incluir los siguientes campos. Este ejemplo muestra solo los campos necesarios para continuar el flujo:
{
"order": {
"payment": {
"data": {
"status": "pending_3ds",
"next_action": {
"action": "authorization_3ds",
"authorization_3ds": {
"url_challenge": "https://api.deuna.io/transactions/next-action/NEXT_ACTION_ID"
}
}
}
}
}
}Utilice estos campos como fuente de verdad:
| campo | Significado | acción |
|---|---|---|
order.payment.data.status | pending_3ds significa que el flujo de pago 3DS no se ha resuelto. | Mantén bloqueada la entrega y gestiona la acción devuelta. |
order.payment.data.next_action.action | Identifica la acción requerida del cliente. | Manejar authorization_3ds con el SDK DEUNA compatible o los datos de desafío devueltos. |
order.payment.data.next_action.authorization_3ds.url_challenge | URL de DEUNA para el siguiente paso de autenticación, que puede incluir comprobaciones del navegador antes de un desafío. | Usa exactamente la URL devuelta en el modo de presentación compatible con la conexión. |
Por compatibilidad, algunas integraciones también pueden recibir un nivel superior authorization_3ds objeto. Las nuevas implementaciones deberían preferir next_action.
3. Presenta la siguiente acción#
SDK Web
Uso initNextAction(...) cuando desee que DEUNA administre el comportamiento modal, iframe o de redireccionamiento admitido. Ver el Referencia del SDK web.
Si un Payment Widget de DEUNA ya gestiona el recorrido del pago, permite que ese widget gestione la acción devuelta. No abras una segunda instancia de Next Action para el mismo intento. Para un formulario de pago propio del comercio, consulta el Widget de Acción Siguiente.
Integración directa del navegador
Si realiza la siguiente acción usted mismo:
- Utilice el devuelto
url_challenge; no construyas una URL 3DS. - Siga el modo de presentación configurado. No fuerce la página de un emisor en un iframe cuando se requiera una redirección de nivel superior.
- Conserve sus URL de éxito, fracaso y retorno.
- Trate una ventana cerrada, una devolución de llamada o un redireccionamiento como una señal para recuperar el estado, no como un pago exitoso.
Aplicaciones nativas
Utilice el SDK DEUNA compatible o un navegador/vista web seguro del sistema. Configure el enlace profundo/devolución y restaure el contexto de pago cuando el comprador regrese a la aplicación.
Comprobaciones del navegador antes de un desafío
La experiencia devuelta puede recopilar señales del navegador y del dispositivo antes de que el emisor decida si solicita un desafío. Este paso no requiere que el cliente ingrese un código ni apruebe un pago. Mantén disponibles la pantalla de carga y la superficie de autenticación hasta que el flujo continúe.
Si la recopilación de datos del navegador no termina dentro de su período de espera, el flujo gestionado puede continuar con ese resultado. Esto por sí solo no significa que la autenticación falló ni que el pago se completó. No sustituyas la acción devuelta por un error basado en un temporizador local ni inicies otra compra.
4. Espere el estado del pago final.#
La finalización de las comprobaciones del navegador, del desafío, una URL de retorno y un callback del SDK son señales para conciliar el pedido original. Ninguna demuestra que se hayan cobrado fondos. La autenticación puede finalizar junto con la autorización, o DEUNA puede necesitar completar el pago después.
Utilice ambos:
- los webhooks de estado de pago configurados y verificados para recibir actualizaciones en el backend; y
- Obtener orden cuando el cliente regresa o cuando su sistema necesita conciliar un resultado incierto.
| Resultado | Significado | Acción de cumplimiento |
|---|---|---|
processed | Compra completada. | Cumplir una vez que pasen los controles de su negocio. |
authorized | Los fondos fueron autorizados pero no capturados. | Siga su estrategia de captura; no lo trate como capturado. |
pending_3ds | El flujo 3DS sigue sin resolverse, con o sin un desafío visible. | Mantén disponible la experiencia actual; no completes la entrega ni reinicies automáticamente. |
pending, processing, o authorizing | El pago aún está en curso. | Continúa la conciliación; no envíes otra compra para finalizar 3DS. |
denied, cancelled, o expired | El pago no se completó. | Mostrar un resultado recuperable y comenzar un nuevo intento sólo cuando sea apropiado. |
Ver Flujo de trabajo y estados de pago para cada estado de pago público y transición.
5. Maneje la autenticación sin fricciones#
Frictionless significa que el cliente no completa ningún desafío del emisor. Aun así, puede requerir la experiencia de navegador devuelta para recopilar señales del dispositivo y permitir que el procesamiento del pago continúe. Tu código debe admitir ambos resultados:
- un estado de pago inmediato final o en curso; o
pending_3dsmás unaauthorization_3dssiguiente acción.
No requiere la presencia de una URL de desafío para determinar si se evaluó 3DS.
Un pago exitoso sin desafío no demuestra por sí solo que la autenticación 3DS haya sido exitosa. Usa los detalles de autenticación reportados cuando sean necesarios para soporte o análisis de responsabilidad.
6. Tiempos de espera y reintentos#
La recopilación de datos del navegador, la carga de la vista del desafío, la autenticación del emisor y el procesamiento del pago tienen períodos de espera distintos. Una demora de carga o un tiempo de espera local agotado no determina el resultado del pago. Confirma la ventana de autenticación aplicable a tu conexión durante la certificación; no establezcas una duración universal fija para los desafíos.
- No reutilice una URL de desafío vencida.
- No cree intentos de pago repetidos mientras el primer pago aún no se haya resuelto.
- Utilice el estado final y
allow_retry/guía de error estandarizada cuando esté disponible antes de ofrecer otro intento. - Si el enrutamiento selecciona otra conexión compatible, deje que DEUNA decida si se puede reutilizar un resultado de autenticación existente.
Tras cerrar una vista, una interrupción de red o un tiempo de espera agotado, consulta el pedido original antes de ofrecer otro intento. Si el pago sigue sin resolverse, muestra un resultado pendiente y continúa la conciliación. Si no fue exitoso, aplica el error y la elegibilidad de reintento reportados. Un cierre del lado del cliente no garantiza la cancelación del pago en el backend.
7. Interprete los detalles de autenticación de forma segura#
DEUNA Admin puede mostrar resultados técnicos de 3DS, como la versión del protocolo, el tipo de flujo, ECI, el resultado de la autenticación y los identificadores de transacciones de red. Úselos para apoyo, reconciliación y análisis de disputas.
No almacene ni exponga criptogramas sin procesar, respuestas de autenticación completa ni cuestione HTML en los registros de comerciantes. Un estado de pago, no un ECI o un evento de finalización de desafío, controla el cumplimiento.