Saltar al contenido principal
POST
Registrar payloads de solicitud, respuesta y webhook del proveedor
Dry-run es una superficie de validación previa a producción. Recibe las llamadas a la API que tu integración envía a un proveedor de pagos (payloads de solicitud, respuesta y webhook). Las correlaciona con la llamada equivalente a la API pública de Yuno que haces en paralelo con el encabezado X-Dry-Run: true. Yuno ejecuta entonces un pipeline de validación automatizado que califica la calidad de la solicitud a la API pública frente al payload del proveedor: campos faltantes, diferencias de estructura, valores de enum incorrectos, metadata sin mapear y cualquier otra inconsistencia que haría que el pago real falle o se comporte de forma distinta una vez que salgas a producción.

Cómo funciona el par

  1. Tu integración hace su llamada normal al proveedor (por ejemplo Stripe, Adyen, dlocal).
  2. Tu integración también llama al endpoint correspondiente de la API pública de Yuno (por ejemplo POST /v1/payments) con el encabezado X-Dry-Run: true. Yuno acepta la solicitud, no la enruta a ningún proveedor y la almacena para compararla.
  3. Tu integración llama a POST /v1/dry-run/provider-events con el intercambio original con el proveedor (solicitud, respuesta, webhook) que acaba de realizar, correlacionado con el mismo merchant_reference.
  4. Yuno empareja los dos registros por merchant_reference + account_id y ejecuta el pipeline de validación. Los resultados están disponibles en el dashboard y mediante GET /v1/dry-run/provider-events/{id} (API de lectura, referencia aparte).
El resultado te indica si la solicitud a la API pública que estás construyendo hoy produciría el mismo comportamiento del proveedor una vez que Yuno empiece a enrutarla, sin tocar dinero de producción ni enviar una transacción real al proveedor a través de Yuno.

Cuándo usarlo

  • Antes del lanzamiento: certifica tu integración con la API pública frente al comportamiento del proveedor que ya tienes funcionando.
  • Migraciones de proveedor: verifica que un nuevo proveedor acepte los campos que Yuno reenvía antes de cambiar el tráfico.
  • Pruebas de regresión: vuelve a ejecutar dry-runs en CI para detectar desviaciones cuando cambian tu integración o el contrato del proveedor.
Una llamada puede incluir hasta 10 entradas de evento (REQUEST, RESPONSE y/o WEBHOOK), todas vinculadas al mismo pago mediante merchant_reference. Consulta las reglas de correlación.
Este endpoint tiene un complemento: POST /v1/payments acepta un encabezado de solicitud X-Dry-Run: true que le indica a Yuno que valide en lugar de enrutar. Ambas partes deben compartir el mismo merchant_reference para que la validación pueda emparejarlas.
Usa X-Idempotency-Key para reintentos seguros. La misma clave con el mismo payload devuelve la respuesta original; la misma clave con un payload distinto devuelve 409.
Límite de PCIheaders y body se envían codificados en base64. Yuno decodifica el base64 al recibirlos, aplica una redacción determinista de PAN/CVV/tokens de autenticación y conserva únicamente la forma redactada. Consulta Cumplimiento de PCI.

Correlation

  • merchant_reference siempre es obligatorio e identifica de forma única la orden de tu lado. Yuno lo usa para asociar el evento con un pago de forma asíncrona cuando no se envía payment_id.
  • payment_id, si se envía, se resuelve de inmediato. Si el id es desconocido para tu cuenta, la solicitud devuelve 404 PAYMENT_NOT_FOUND.
  • provider_id + payment_method_type identifican de forma opcional qué superficie de integración ejercita el dry-run (por ejemplo stripe + CREDIT_CARD). Si se omiten, Yuno usa la información del pago asociado.

Encabezados

PUBLIC-API-KEY
string

Clave de API pública. Se requiere una de las dos: PUBLIC-API-KEY o PRIVATE-SECRET-KEY.

PRIVATE-SECRET-KEY
string

Clave secreta privada para llamadas de servidor a servidor. Se requiere una de las dos: PUBLIC-API-KEY o PRIVATE-SECRET-KEY.

X-Idempotency-Key
string

Cadena de formato libre (MAX 64). Ventana de repetición de 24 horas.

Maximum string length: 64

Cuerpo

application/json
merchant_reference
string
requerido

Identificador asignado por el comercio (MAX 255; MIN 3). Único por cuenta.

Required string length: 3 - 255
Ejemplo:

"ORD-12345"

events
object[]
requerido

De 1 a 10 entradas de intercambio HTTP para esta simulación (MAX 10; MIN 1).

Required array length: 1 - 10 elements
Ejemplo:
payment_id
string<uuid>

UUID del pago de Yuno. Si se envía, se resuelve de inmediato.

Ejemplo:

"fb9e5fa4-684c-4747-9755-9d332617f16f"

account_id
string<uuid>

UUID de la cuenta de Yuno, con el mismo formato que account_id en POST /v1/payments.

Ejemplo:

"a389f417-ecd1-4355-89f5-7489564f264d"

provider_id
enum<string>

Identificador del proveedor. Los valores permitidos están alineados con el catálogo de Yuno.

Opciones disponibles:
STRIPE,
ADYEN,
CYBERSOURCE,
BRAINTREE,
NMI,
CHECKOUT,
WORLDPAY,
PAYPAL,
EBANX,
GLOBALPAYMENTS,
NUVEI,
CIELO,
MPGS,
PRISMA,
FISERV,
WORLDLINE,
ANTOM,
ORBITAL,
GOCARDLESS,
AUTHORIZE_NET,
SONY,
CITI,
EPX,
HPAY,
PAYSTACK,
PLAID,
SAFERPAY,
SIKA_HEALTH,
VALIDIFI,
WEPAY,
CARD_CONNECT,
GMO_PG,
MONERIS,
BLUESNAP,
QUICK_GATEWAY,
TWENTYFOUR_HOUR_FITNESS,
MERCHANT_ESOLUTIONS,
NETS,
FAT_ZEBRA,
WINDCAVE,
CHASE_MOBILITY,
HELIX,
ANB,
AMAZON_PAY,
OPAYO,
IP_PAYMENTS,
KLARNA,
BILLDESK,
WELLS_FARGO,
SAGEPAY,
PLANET
Ejemplo:

"STRIPE"

payment_method_type
enum<string>

Método de pago que ejercita esta simulación. Mismo vocabulario que payment_method.type en POST /v1/payments.

Opciones disponibles:
,
CARD,
CREDIT_CARD,
CREDIT_CARD_REFERENCE_TRANSACTION,
DEBIT_CARD,
EPX_TOKEN,
TEST_CREDIT_CARD,
UPC_TOKEN_TRANSACTION,
APPLE_PAY,
GOOGLE_PAY,
PIX,
PSE,
OXXO,
BOLETO,
ALI_PAY,
AMAZON_PAY,
GCASH,
IDEAL,
KAKAO_PAY,
KLARNA,
MOMO_PAY,
NAVER_PAY,
OVO,
PAYPAL,
PAYPAL_CREDIT,
PAYPAY,
PAZE,
TOSS_PAY,
UPI,
VENMO,
ACH,
BANK_TRANSFER,
CRYPTO,
CASH
Ejemplo:

"CREDIT_CARD"

Respuesta

Simulación registrada

id
string
requerido

Identificador público del registro de la simulación (nano_id, 21 caracteres).

Ejemplo:

"drun_1209fnkw428ufwd"

status
enum<string>
requerido

Estado del ciclo de vida.

Opciones disponibles:
REGISTERED
Ejemplo:

"REGISTERED"

merchant_reference
string
requerido
Ejemplo:

"ORD-12345"

payment_id
string<uuid> | null
Ejemplo:

"fb9e5fa4-684c-4747-9755-9d332617f16f"

account_id
string<uuid> | null
Ejemplo:

"a389f417-ecd1-4355-89f5-7489564f264d"

provider_id
string
Ejemplo:

"STRIPE"

payment_method_type
enum<string>
Opciones disponibles:
,
CARD,
CREDIT_CARD,
CREDIT_CARD_REFERENCE_TRANSACTION,
DEBIT_CARD,
EPX_TOKEN,
TEST_CREDIT_CARD,
UPC_TOKEN_TRANSACTION,
APPLE_PAY,
GOOGLE_PAY,
PIX,
PSE,
OXXO,
BOLETO,
ALI_PAY,
AMAZON_PAY,
GCASH,
IDEAL,
KAKAO_PAY,
KLARNA,
MOMO_PAY,
NAVER_PAY,
OVO,
PAYPAL,
PAYPAL_CREDIT,
PAYPAY,
PAZE,
TOSS_PAY,
UPI,
VENMO,
ACH,
BANK_TRANSFER,
CRYPTO,
CASH
Ejemplo:

"CARD"

operation_type
string
Ejemplo:

"PURCHASE"