Protección ante rechazo del destino y reintentos seguros

​

Qué protege este flujo

​

Secuencia segura

1. Si la primera respuesta es ambigua, repite la solicitud exacta con la misma idempotency_key. Devuelve el recurso original con idempotency_hit: true; nunca crea un segundo payout.
2. Si la respuesta es destination_recently_rejected, la clave original no se consumió. Revisa el rechazo bancario y decide si corresponde reintentar el destino.
3. Un reintento deliberado usa una clave de idempotencia nueva y options.destination_retry_ack con el ID del payout rechazado más reciente.
4. Reutilizar la clave anterior con opciones cambiadas devuelve 409 idempotency_conflict; nunca modifica la operación original.
5. Un destino sin rechazo reciente, o un payout de otro corredor, sigue su validación y despacho normal.

​

Request de reintento deliberado

{
  "country": "CL",
  "currency": "CLP",
  "method": "bank_transfer",
  "amount": "1000.00",
  "beneficiary": {
    "name": "Example Recipient",
    "bank_code": "012",
    "account_number": "123456789",
    "tax_id": "11111111-1"
  },
  "options": {
    "destination_retry_ack": "<prior_case_id>"
  },
  "idempotency_key": "payout-retry-0001"
}

​

Ejemplos de respuesta

​

Rechazo reciente

{
  "error": "destination_recently_rejected",
  "message": "destination was rejected by the bank on 2026-01-15 (prior case <prior_case_id>, code <prior_code>); retry with a new idempotency_key and options.destination_retry_ack=<prior_case_id> to confirm"
}

​

Opciones cambiadas con la clave anterior

{
  "error": "idempotency_conflict",
  "message": "the idempotency key was already used with a different request"
}

​

Estados y acciones

​

Preguntas frecuentes