Saltar al contenido principal

Idempotencia

Las operaciones que crean o mueven dinero exigen el header Idempotency-Key. Con él puedes reintentar sin miedo: si la primera llamada ya se procesó, la repetición devuelve la misma respuesta y no se crea nada nuevo.

Operación¿Exige Idempotency-Key?
POST /v1/payment-intentssí
POST /v1/payment-intents/{id}/checkoutsí
POST /v1/payments/{paymentId}/refundssí
Consultas (GET)no

Reglas​

  • Una clave por operación lógica. Usa un UUID nuevo por cada cobro, checkout o devolución, y guárdalo junto a tu orden para poder reintentar con la misma clave.
  • Misma clave, mismo body. Reusar una clave con otro body responde 409 IDEMPOTENCY_CONFLICT.
  • Vigencia de 24 horas. Pasado ese plazo la clave puede volver a usarse como nueva.
  • Solo se recuerdan los éxitos. Si la llamada terminó en error (validación, proveedor no disponible…), reintentar con la misma clave vuelve a intentar la operación.
  • Por aplicación. Dos aplicaciones distintas pueden usar la misma clave sin chocar.
  • Sin el header, la llamada responde 400 VALIDATION_ERROR.

Cuándo reintentar​

Resultado¿Reintentar con la misma clave?
Timeout, error de red, 5xxsí, con backoff
429 RATE_LIMIT_EXCEEDEDsí, después de details.retry_after_seconds
503 CONNECTOR_UNAVAILABLEsí, más tarde (el proveedor no está disponible)
400, 401, 404, 409, 422no: corrige el request o reobtén el recurso

Del lado de tu sistema​

Los webhooks también pueden llegar más de una vez. Usa el id del evento (X-Pay-Event-Id) como clave única al procesarlos. Ver Webhooks.