Idempotencia y manejo de errores

Idempotencia

Toda operación que crea un cobro (POST /v1/payments, POST /v1/payment_links/{id}/pay) requiere el header Idempotency-Key:

Idempotency-Key: 6e4b6f0a-a5f0-4b9a-9b8b-1a2b3c4d5e6f

• Debe tener al menos 8 caracteres. Un UUID v4 es una buena opción.
• Usa una llave distinta por cada intento de cobro real, y la misma llave si estás reintentando la misma petición (por ejemplo, tras un timeout de red).
• Si falta el header, la petición se rechaza con 400 idempotency_key_required antes de intentar nada.

Sin esto, un reintento por timeout de tu lado podría crear dos cobros para el mismo intento del cliente — el mecanismo de idempotencia de Paytami evita exactamente ese caso.

Formato de un error

Todo error de la API pública tiene la misma forma:

{
  "error": {
    "code": "amount_below_minimum",
    "message": "El monto mínimo es 1000"
  }
}

Usa siempre error.code para lógica de programa — error.message es texto legible para humanos y puede cambiar de redacción sin previo aviso.

Catálogo de códigos de error

Código	HTTP	Significado
unauthorized	401	La api_key falta, es inválida, fue revocada o expiró.
validation_error	400	El cuerpo o los parámetros de la petición no cumplen el formato esperado.
idempotency_key_required	400	Falta el header Idempotency-Key, o mide menos de 8 caracteres.
idempotency_key_reused	409	Ya existe un cobro distinto creado con esa misma llave de idempotencia.
amount_below_minimum	400	El monto es menor al mínimo permitido para esa moneda o enlace.
amount_above_maximum	400	El monto excede el máximo permitido para esa moneda o enlace.
amount_required	400	El enlace de pago es de monto variable y no se indicó amount.
currency_not_supported	400	La moneda no está habilitada para tu comercio.
method_not_supported	400	El método de pago no está disponible para esa moneda o comercio.
unknown_payment	404	El id de pago no existe, o no pertenece al comercio autenticado.
unknown_payment_link	404	El enlace de pago no existe.
payment_not_payable	409	El pago ya no admite cobro (ya se pagó, venció, o se canceló).
payment_link_not_payable	409	El enlace ya no admite pago (venció, se agotó, o está inactivo).
payment_not_refundable	400	El pago no está en un estado que admita reembolso.
refund_amount_exceeds_remaining	400	El monto a reembolsar excede lo que queda disponible del cobro.
rate_limited	429	Demasiados intentos sobre un enlace de pago en poco tiempo.
processor_unavailable	503	El procesamiento no está disponible en este momento — reintenta más tarde.
internal_error	500	Error inesperado del lado de Paytami.

TIP

Este catálogo es cerrado y propio de Paytami. Si ves un código que no está en esta tabla, repórtalo — no es un caso que debas manejar como si fuera parte del contrato.

Estados de un pago

status en la respuesta de un Payment es siempre uno de estos valores:

Estado	Significado
created	El cobro se creó y espera que el cliente complete el pago.
processing	El cliente está completando el pago (por ejemplo, una transferencia bancaria en curso).
authorized	El método de pago autorizó el cobro, pendiente de captura.
captured	El dinero fue capturado del cliente.
pending_settlement	Pendiente de liquidación hacia Paytami.
settled_to_paytami	Paytami ya recibió los fondos.
available_to_merchant	Los fondos están disponibles para tu comercio.
partially_refunded	Se reembolsó parte del monto original.
refunded	Se reembolsó el monto total.
chargeback	El cliente disputó el cobro ante su banco/emisor.
failed	El intento de pago falló.
canceled	El cobro se canceló antes de completarse.
expired	El cobro venció sin que el cliente completara el pago.

Para efectos de "¿puedo redirigir al cliente a pagar esto?", solo created, processing y authorized admiten pago — cualquier otro estado significa que el cobro ya se resolvió, de una forma u otra.