Idempotencia, reintentos y duplicados

Estado documental: Implementado y verificado en Producción para Web Checkout.

Objetivo

Evitar que un retry técnico cree otra operación cuando el backend no sabe si YUPY procesó una solicitud anterior.

Identidades

Identificador	Responsabilidad
`Idempotency-Key`	Identifica el intento lógico de creación y permite retry seguro.
`source_reference`	Referencia externa opcional/recomendada del negocio.
`checkout_uid`	Identidad YUPY del Web Checkout.
`payment_order_uid`	Identidad canónica YUPY de la Payment Order.

No son intercambiables.

Request

POST https://api.yupy.us/v1/checkouts
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: <UNIQUE_KEY>

{
  "amount": "85.50",
  "currency": "PEN",
  "payment_method": "qr",
  "source_reference": "ORDER-10482"
}

Misma key + mismo payload lógico

→ misma operación lógica
→ mismo checkout_uid
→ mismo payment_order_uid
→ no crear otro checkout
→ no crear otra Payment Order

YUPY puede reemitir o rotar el checkout token durante replay. Si se reemite, el token anterior deja de ser válido. El integrador debe utilizar la checkout_url más reciente devuelta.

Misma key + payload incompatible

→ conflicto de idempotencia
→ no reutilizar la key para otra operación lógica

Retry después de timeout de red

Intento 1:
source_reference = ORDER-10482
Idempotency-Key = checkout-order-10482-1

No hubo respuesta

Intento 2:
source_reference = ORDER-10482
Idempotency-Key = checkout-order-10482-1
mismo payload lógico

Qué debe persistir el backend

source_reference
Idempotency-Key
checkout_uid
payment_order_uid
estado conocido

checkout_url es credencial temporal y no debe registrarse completa en logs públicos.

Idempotencia no confirma pago

Idempotency-Key
→ protege creación

POO / conciliación
→ determina estado financiero

API Technical Docs