Toda operación que mueve dinero exige una clave de idempotencia. La
tabla completa:
Cómo enviarla
Dos formas equivalentes (si mandas ambas, gana el body):
Si la omites recibes 400 idempotency_key_required.
Qué pasa al reintentar
La clave es única por cuenta origen. Si repites una llamada con la misma
clave:
- No se crea una operación nueva ni se mueve dinero otra vez.
- Recibes
200 OK (en vez de 201/202) con el objeto original más el
campo idempotency_hit: true.
¿Con qué clave reintento?
La regla de decisión completa, para no dudar nunca:
Recomendaciones
- Usa un identificador de tu sistema (ID de orden, de nómina, etc.), no
un timestamp ni un UUID generado al vuelo en cada retry.
- Guarda la clave antes de llamar a la API; así puedes reintentar tras un
timeout con garantía de no duplicar.
- Ante un error de red o
5xx, reintenta con la misma clave. Ante un
4xx de validación, corrige el request y usa una clave nueva.
La clave vuelve a ti
Los webhooks de la operación traen tu clave de vuelta como
idempotency_key (payout_status_changed, payin_credited,
payin_settlement_scheduled, payin_expired, payin_refunded,
crypto_withdrawal_status_changed, wallet_send_status_changed), y el
recurso payin la devuelve en GET /v1/payins/{id} — concilia las
notificaciones contra tu propia referencia sin una consulta extra. El
campo se omite cuando la operación se creó sin clave (o la creó la propia
plataforma — las claves internas jamás se exponen). transfer_received
no la lleva. Ver
Webhooks. Última modificación el 3 de octubre de 2026
