Idempotencia y reintentos

La clave de idempotencia

POST /v2/payins y POST /v2/payouts exigen la cabecera Idempotency-Key (8 a 128 caracteres). Reenviar el mismo pedido con la misma clave devuelve la misma operación, con el estado que tenga en ese momento, y no le pide nada nuevo al banco ni otro código a su usuario. La misma clave con otro cuerpo es 409 idempotency_key_reused.

Derive la clave de su identificador de orden (orden-4821), no de la hora ni de un azar: así un reintento desde un proceso nuevo manda la misma clave. Si usa un SDK y no pasa una clave, el SDK genera una, la reutiliza en cada reintento y se la devuelve con la operación creada: guárdela junto a su orden.

Qué se reintenta solo, y qué no

Situación	Qué hacer
Error de red antes de recibir respuesta, 429, 5xx en un GET	Reintentar con espera creciente. Nada se movió.
Lo mismo en un POST con Idempotency-Key	Reintentar con la misma clave. Es seguro por definición.
POST .../confirm, .../resend-code, .../cancel, /v2/webhook-endpoints	No reintentar a ciegas. Consulte la operación con GET y decida.
503 temporarily_unavailable en .../cancel	El pago sigue pendiente. Consulte; el sistema lo resuelve solo.
4xx (validación, alcance, no encontrado)	Corrija el pedido. Reintentar igual da lo mismo.

Los SDK aplican exactamente esta tabla: tres intentos por omisión, espera exponencial con azar, y nunca un reintento que pueda mover dinero dos veces.

Un resultado pendiente se resuelve solo

Si una operación queda pending con pending_reason: processing, la API la consulta al proveedor hasta la respuesta final y le avisa por webhook. Usted no necesita consultar en bucle; si lo hace, GET /v2/transactions/{id} no le cuesta nada ni le pide nada al banco.