Detalle de falla

El contrato de la order no tiene un campo substatus. Cuando una Order tiene status: "FAILED", el detalle adicional viaja en dos campos de la orden, ambos strings libres y nulleables: failure_code y failure_reason.

Campos

Campo	Tipo	Descripción
failure_code	string | null	Código breve y de formato libre que identifica la causa. No es un catálogo cerrado — trátalo como una etiqueta opaca para logging/soporte, no como un valor sobre el que hacer un switch exhaustivo.
failure_reason	string | null	Explicación en lenguaje humano de la falla.

Se pueblan en las lecturas (GET /orders/{id}, GET /orders) cuando algo sale mal; la respuesta del POST /orders inicial puede no traerlos todavía, porque la orden no llegó a un estado terminal en ese momento.

Dos cosas para programar a la defensiva:

• FAILED no es el único status que los trae. Una orden que falló y tuvo devolución de fondos reporta status: "COMPENSATED" con el failure_code de la falla original todavía adjunto. No condiciones la lectura de estos campos a status === "FAILED".
• failure_reason puede venir string vacío, no solo null. Una verificación como reason === null no lo detecta; usa una verificación por falsy.

Ejemplo

{
  "id": "cpg_txn_a1b2c3d4e5f6",
  "status": "COMPENSATED",
  "failure_code": "PROVIDER_CANCELLED",
  "failure_reason": ""
}

El mismo par llega en el webhook

No hace falta que hagas polling para ver esto. El webhook de estado de la orden trae los mismos dos valores con otros nombres:

En la orden	En el evento del webhook
failure_code	reason
failure_reason	message

Los mismos strings, la misma fuente, sin traducción en el medio. Lo que aprendas a reconocer en un lado sirve en el otro.

Códigos de falla de pago (RET-*)

Cuando un pago se rechaza en la red de dispersión, failure_code trae un código RET-. Vienen de nuestra plataforma de pagos de siempre y su significado no cambió, así que es seguro reconocerlos — pero lee la advertencia debajo de la tabla antes de construir sobre ellos.

Código	Qué pasó	La causa está en
RET-001	El teléfono ingresado no es válido, no está registrado, o no puede recibir pagos.	Datos del beneficiario
RET-002	El intento de transacción expiró por tiempo de espera o respuesta del proveedor.	Proveedor
RET-003	El tipo de cuenta del destinatario es incorrecto o no válido para esta operación.	Datos del beneficiario
RET-004	El tipo de persona asociado al destinatario no es válido según los criterios definidos.	Datos del beneficiario
RET-005	La transacción fue rechazada por no ser válida o no estar autorizada.	Proveedor
RET-006	El destinatario canceló la transacción antes de completarse.	Destinatario
RET-007	El servicio no está disponible actualmente o solo opera en modalidad presencial (taquilla).	Proveedor
RET-008	Inconsistencias entre el teléfono y la cédula/RIF del destinatario o no está registrado.	Datos del beneficiario
RET-009	Uno o más campos tienen errores de formato. Verifica los datos ingresados.	Datos del beneficiario
RET-010	La institución financiera seleccionada no se encuentra disponible en este momento.	Proveedor
RET-012	La cédula o RIF del destinatario es inválido.	Datos del beneficiario
RET-013	La cuenta bancaria del destinatario no es válida o no está registrada.	Datos del beneficiario
RET-018	La nacionalidad de la cédula/RIF ingresada no es válida.	Datos del beneficiario
RET-019	La red de autorización no está disponible actualmente.	Proveedor
RET-020	Los datos ingresados contienen errores o no cumplen con los requisitos esperados.	Datos del beneficiario
RET-026	El número del destinatario es incorrecto o no está afiliado al sistema.	Datos del beneficiario
RET-028	El saldo disponible es insuficiente para completar la transacción.	Balance
RET-029	El banco destino no está afiliado, autorizado o activo para pagos móviles.	Proveedor
RET-033	La transacción excede el monto diario permitido por el sistema.	Límites
RET-034	La transacción excede el monto mensual permitido.	Límites
RET-035	Se ha excedido la cantidad diaria de pagos permitida.	Límites
RET-036	Se ha excedido la cantidad mensual de pagos permitida.	Límites
RET-044	La cuenta bancaria del destinatario se encuentra cerrada.	Datos del beneficiario
RET-045	La cuenta bancaria del destinatario está inactiva.	Datos del beneficiario
RET-050	El monto ingresado excede el máximo permitido para una transacción.	Límites
RET-055	El teléfono no está habilitado para recibir pagos.	Datos del beneficiario
RET-056	El monto de la operación supera el límite máximo permitido.	Límites
RET-9999	Se produjo un error inesperado. Intenta nuevamente o contacta a soporte.	Desconocido

"La causa está en" es una ayuda de lectura, no un campo. Es nuestro agrupamiento de las descripciones de arriba, para ahorrarte clasificar 28 filas a mano; la API no devuelve nada de eso. Datos del beneficiario significa que un payment_instructions corregido puede funcionar. Límites y Balance significan que la request estaba bien formada pero no se aceptó. Proveedor significa que reintentar más tarde puede funcionar y no hay nada que cambiar de tu lado.

nota

failure_code y failure_reason son strings de formato libre, no un catálogo de errores fijo — para el contrato de error estructurado que devuelven las llamadas fallidas a la API (respuestas 4xx/5xx), ver Códigos de error.