Flujo de trabajo y estados de pago
Comprenda cada estado de pago público, las operaciones que lo producen y las transiciones que deben manejar los comerciantes.
En esta página
Uso payment.data.status como fuente de verdad para un pago. Cuando el pago esté incluido en una respuesta de pedido o un webhook, lea order.payment.data.status. El contenedor del pedido no cambia el significado del estado de pago.
Evalúe siempre el estado junto con los montos confirmados y el historial de operaciones. Una solicitud API aceptada o un HTTP 2xx la respuesta puede significar que se inició una operación asincrónica; No siempre significa que el dinero se haya movido.
Para decisiones sobre fraude, consulte Flujo de trabajo y estados de fraude. Para la entrega y verificación de notificaciones, consulte Webhooks de DEUNA.
Familias de estado#
Las etiquetas a continuación explican cómo los comerciantes deben manejar los valores; no son campos API adicionales.
| familia | Estados | Manejo comercial |
|---|---|---|
| Esperando acción o confirmación | pending, pending_3ds, processing, authorizing, capturing, partial_capturing, voiding, refunding, partial_refunding, manual_review | Mantener el pago sin resolver. Complete cualquier acción requerida por el cliente y espere o recupere un resultado autorizado. |
| Confirmado y aún operativo. | processed, authorized, captured, partial_captured, partial_refunded | Registre el resultado financiero confirmado. Una captura, un reembolso o una anulación elegibles posteriores aún pueden cambiar el estado. |
| Fracasado pero recuperable | denied | No cumplas con este intento. Una decisión de reintento o enrutamiento puede hacer que el mismo pago vuelva a estar activo, por lo que no modele denied como terminales. |
| Cancelación en espera de resolución financiera | cancelled | Inspeccionar la actividad financiera anterior. Aún puede seguir un reembolso o una anulación. |
| terminales | voided, refunded, expired | La máquina de estado de pago central no tiene ninguna transición saliente desde estos valores. |
partial_captured y partial_refunded puede ser el último estado requerido por el proceso comercial del comerciante aunque no sean estados de API de terminal. Mantener el estado real y los montos acumulados; nunca reemplace un estado parcial localmente con captured o refunded.
Ciclo de vida de extremo a extremo#
Esta descripción general muestra las principales familias del ciclo de vida. Las transiciones directas y las sucursales específicas del proveedor se enumeran en la referencia de transición validada.
3DS y OTP
pending_3ds significa que la autenticación está incompleta. El éxito de la autenticación sólo permite que continúe el flujo de pago; no prueba que la compra o autorización haya tenido éxito. Después del desafío, espera processed, authorizedu otro estado de pago informado.
Algunos adaptadores de procesador utilizan pending_otp internamente. El procesamiento de pagos actual normaliza ese resultado al público. pending y proporciona los metadatos necesarios para la siguiente acción. Si un informe o filtro de búsqueda anterior contiene pending_otp, trátelo como si estuviera esperando la acción del cliente, no como si el pago fuera exitoso.
Autorización, captura y nulidad#
El procesamiento de pagos en dos pasos reserva los fondos primero y los cobra después. authorized No es dinero capturado.
La máquina de estados también permite que un procesador informe captured, partial_capturedo voided directamente sin exponer primero el estado "-ing" coincidente. Las notificaciones son instantáneas del estado autorizado, no una secuencia garantizada de evento por evento.
Elija compra en un solo paso o autorización/captura en dos pasos en el nivel de conexión del procesador. La captura y anulación de la elegibilidad también depende del procesador, la cantidad restante, el momento y la configuración del comerciante. Su DEUNA TAM puede confirmar un comportamiento compatible.
Para modos de captura parcial y final_capture, ver MPC: capturas parciales múltiples. el exitoso API nula devuelve HTTP 204 No Content; utilice el estado de pago posterior cuando el procesador complete de forma asincrónica.
Reembolsos y cancelación#
Los reembolsos devuelven los fondos recaudados. Las anulaciones liberan una autorización. No son intercambiables.
Un reembolso fallido puede restaurar el estado financiero anterior (processed, capturedo partial_captured). Conserve por separado el pago exitoso y el intento de reembolso fallido. Ver MPR: Reembolsos parciales múltiples para modalidades de devolución parcial nativa y agregada por DEUNA.
flujo de trabajo APM#
Los métodos de pago alternativos comúnmente comienzan en pending, puede exponer processing, y completar en processed, denied, cancelledo expired. Algunas conexiones APM admiten autorización y captura, por lo que se pueden aplicar los mismos estados de autorización.
La fecha límite de pago depende del método y de la configuración. no inferir expired desde el momento del navegador o un retorno de redirección; esperar hasta que la DEUNA lo informe.
Referencia del estado del pago#
Los valores son cadenas en minúsculas que distinguen entre mayúsculas y minúsculas.
| Estado | Significado | Lo que debe hacer el comerciante |
|---|---|---|
pending | Pago creado; Es posible que aún sea necesaria la acción del cliente, la ruta o la confirmación del proveedor. | Seguir next_action o instrucciones del método y mantener bloqueado el cumplimiento. |
pending_3ds | La autenticación 3DS está incompleta. | Complete el desafío y luego evalúe el estado de pago resultante. |
processing | Hay una compra o un pago APM en curso. | Espere un webhook o recupere el resultado autorizado antes de volver a intentarlo. |
processed | Una compra de un solo paso completada. | Registrar el éxito y aplicar la política de cumplimiento; pueden seguir reembolsos. |
authorizing | La solicitud de autorización está en curso. | No trate los fondos como capturados o reservados todavía. |
authorized | Los fondos se reservaron exitosamente. | Captar o anular cuando sea elegible. |
capturing | Se está realizando una captura completa. | Realice un seguimiento de la operación y espere la confirmación. |
partial_capturing | Se está realizando una captura parcial. | Mantenga separadas las cantidades capturadas pendientes y confirmadas. |
partial_captured | Se capturó una cantidad parcial. | Registre el monto confirmado y la elegibilidad restante para captura/reembolso. |
captured | Captura completada. | Registre el monto recaudado; pueden seguir reembolsos. |
voiding | La liberación de una autorización está en curso. | Esperar voided o un resultado restaurado/fallido. |
voided | La autorización fue liberada. | Registro de finalización del terminal. |
refunding | Se está realizando un reembolso total o del saldo restante. | Espere la confirmación; La aceptación de la solicitud no es prueba de la devolución de los fondos. |
partial_refunding | Se está realizando un reembolso parcial. | Realice un seguimiento de los importes reembolsados pendientes y confirmados por separado. |
partial_refunded | Un reembolso parcial completado. | Registre el monto y el saldo reembolsable restante. |
refunded | Se devolvió el saldo reembolsable representado por el ciclo de vida. | Registro de finalización del terminal. |
manual_review | El pago se retiene para una decisión de riesgo. | Mantenga el cumplimiento bloqueado hasta que el pago reciba un nuevo estado. |
denied | El intento actual fue rechazado. | No cumplir. Preservar la razón; un reintento configurado puede volver a ingresar al flujo activo. |
cancelled | El método o comerciante canceló el pago. | Verifique si aún se debe completar un reembolso o una anulación. |
expired | La ventana de finalización permitida se cerró antes de que finalizara el pago. | Registro de finalización de la terminal; crear un nuevo pago si el cliente vuelve a intentarlo. |
not_authorized y failed son utilizados por procesador o adaptadores de nivel de operación, pero no son valores canónicos en el núcleo payment.data.status gráfico de transición. No combine estados de operación del proveedor, estados de operación de captura/reembolso ni marcadores de tiempo de espera locales en el campo de estado de pago.
Referencia de transición validada#
Las siguientes transiciones coinciden con la máquina de estado central de Pagos. Se omite la entrega repetida del mismo estado salvo aceptación expresa. Una transición enumerada no garantiza que cada procesador o método de pago admita la operación correspondiente.
| Estado actual | Próximos estados permitidos |
|---|---|
pending | pending, pending_3ds, authorizing, authorized, processing, processed, cancelled, voided, denied, manual_review, expired |
pending_3ds | pending_3ds, authorizing, authorized, processing, processed, cancelled, denied, manual_review, expired |
processing | processed, cancelled, denied, manual_review, partial_refunding, refunding, partial_refunded, refunded |
processed | refunding, refunded, partial_refunding, partial_refunded, voided |
authorizing | authorized, captured, voiding, cancelled, denied, manual_review |
authorized | capturing, captured, partial_capturing, partial_captured, voiding, voided, cancelled |
capturing | captured, denied; para flujos de recuperación de captura pendientes soportados: authorized, partial_capturing, partial_refunding, partial_refunded, refunding, refunded |
partial_capturing | capturing, partial_captured, captured, denied |
partial_captured | captured, partial_refunding, partial_refunded, refunding, refunded |
captured | partial_refunding, partial_refunded, refunding, refunded |
voiding | voided, denied, authorized |
refunding | refunded, partial_refunded, voided, processed, captured |
partial_refunding | partial_refunded, refunding, refunded, denied, processed, captured, partial_captured |
partial_refunded | partial_refunding, refunding, refunded |
manual_review | processed, captured, denied |
denied | pending, pending_3ds, processing, processed, authorizing, authorized, manual_review, denied |
cancelled | refunded, voided |
voided | Ninguno (terminal) |
refunded | Ninguno (terminal) |
expired | Ninguno (terminal) |
La conciliación del archivo de liquidación puede permitir transiciones de recuperación adicionales mientras DEUNA concilia el resultado de un procesador externo. Estas transiciones no cambian el significado público de los estados.
Algunos perfiles de procesadores pueden aceptar un reembolso mientras una captura asíncrona aún está pendiente. En este flujo, DEUNA puede cancelar o revertir la captura pendiente y reembolsar la autorización original, lo que permite las transiciones adicionales enumeradas para capturing. No inicie este flujo a menos que DEUNA haya confirmado el soporte para la conexión del procesador.
Maneja las actualizaciones de forma segura#
- Verifique cada notificación con el método de verificación de webhook configurado.
- Identifique el pago y la operación relacionada antes de cambiar de estado local.
- Almacene el estado reportado, monto confirmado, moneda, identificador de operación y referencias de proveedores.
- Procese notificaciones repetidas de forma idempotente. No realice la deduplicación únicamente por estado.
- Mantenga el cumplimiento bloqueado para estados transitorios, de revisión o desconocidos.
- Concilie los resultados faltantes o contradictorios a través del flujo de recuperación de pagos admitido.
Un tiempo de espera de HTTP, una respuesta perdida o un webhook tardío no prueban denied o expired. Seguir orientación de solicitud idempotente, recuperar el pago y distinguir un reintento de la misma solicitud de un nuevo intento de pago.