> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Registrar un evento de proveedor en dry-run

> Registra payloads de solicitud, respuesta o webhook del proveedor para validación previa a producción.

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.

> [!NOTE]
>
> 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](#correlation).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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`.

> [!WARNING]
>
> **Límite de PCI**
>
> `headers` 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](https://docs.y.uno/es/docs/security-and-compliance/pci-compliance.md).

***

## 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.


## OpenAPI

````yaml openapi/es/dry-run/register-dry-run-provider-event.json POST /dry-run/provider-events
openapi: 3.1.0
info:
  title: Yuno Dry-Run API
  version: '1.0'
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security: []
paths:
  /dry-run/provider-events:
    post:
      summary: Registrar payloads de solicitud, respuesta y webhook del proveedor
      description: >
        Almacena el tráfico HTTP que el comercio intercambió directamente con un
        proveedor

        de pagos (solicitud, respuesta y webhook) para correlacionarlo con un
        pago de Yuno.
      operationId: registerDryRunProviderEvent
      parameters:
        - in: header
          name: PUBLIC-API-KEY
          schema:
            type: string
          description: >-
            Clave de API pública. Se requiere una de las dos: PUBLIC-API-KEY o
            PRIVATE-SECRET-KEY.
        - in: header
          name: PRIVATE-SECRET-KEY
          schema:
            type: string
          description: >-
            Clave secreta privada para llamadas de servidor a servidor. Se
            requiere una de las dos: PUBLIC-API-KEY o PRIVATE-SECRET-KEY.
        - in: header
          name: X-Idempotency-Key
          schema:
            type: string
            maxLength: 64
          description: Cadena de formato libre (MAX 64). Ventana de repetición de 24 horas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DryRunRequest'
      responses:
        '201':
          description: Simulación registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryRunResponse'
        '400':
          description: Falla de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Credenciales faltantes o no válidas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pago no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Repetición de idempotencia con un payload distinto
        '413':
          description: El payload o el lote supera los límites de tamaño
        '415':
          description: Content-Type no admitido (debe ser application/json)
        '429':
          description: Se superó el límite de solicitudes
components:
  schemas:
    DryRunRequest:
      type: object
      required:
        - merchant_reference
        - events
      properties:
        merchant_reference:
          type: string
          minLength: 3
          maxLength: 255
          description: >-
            Identificador asignado por el comercio (MAX 255; MIN 3). Único por
            cuenta.
          example: ORD-12345
        payment_id:
          type: string
          format: uuid
          description: UUID del pago de Yuno. Si se envía, se resuelve de inmediato.
          example: fb9e5fa4-684c-4747-9755-9d332617f16f
        account_id:
          type: string
          format: uuid
          description: >-
            UUID de la cuenta de Yuno, con el mismo formato que account_id en
            POST /v1/payments.
          example: a389f417-ecd1-4355-89f5-7489564f264d
        provider_id:
          type: string
          description: >-
            Identificador del proveedor. Los valores permitidos están alineados
            con el catálogo de Yuno.
          example: STRIPE
          enum:
            - 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
        payment_method_type:
          type: string
          description: >-
            Método de pago que ejercita esta simulación. Mismo vocabulario que
            payment_method.type en POST /v1/payments.
          example: CREDIT_CARD
          enum:
            - ''
            - 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
        events:
          type: array
          minItems: 1
          maxItems: 10
          description: >-
            De 1 a 10 entradas de intercambio HTTP para esta simulación (MAX 10;
            MIN 1).
          items:
            $ref: '#/components/schemas/Event'
          example:
            - type: REQUEST
              http_method: POST
              operation_type: PURCHASE
              base_url: https://api.stripe.com
              endpoint: /v1/charges
              headers: eyBDb250ZW50LVR5cGU6IGFwcGxpY2F0aW9uL2pzb24gfQ==
              body: eyBhbW91bnQ6IDIwMDAsIGN1cnJlbmN5OiAidXNkIiB9
    DryRunResponse:
      type: object
      required:
        - id
        - status
        - merchant_reference
      properties:
        id:
          type: string
          description: >-
            Identificador público del registro de la simulación (nano_id, 21
            caracteres).
          example: drun_1209fnkw428ufwd
        status:
          type: string
          enum:
            - REGISTERED
          description: Estado del ciclo de vida.
          example: REGISTERED
        merchant_reference:
          type: string
          example: ORD-12345
        payment_id:
          type: string
          format: uuid
          nullable: true
          example: fb9e5fa4-684c-4747-9755-9d332617f16f
        account_id:
          type: string
          format: uuid
          nullable: true
          example: a389f417-ecd1-4355-89f5-7489564f264d
        provider_id:
          type: string
          example: STRIPE
        payment_method_type:
          type: string
          example: CARD
          enum:
            - ''
            - 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
        operation_type:
          type: string
          example: PURCHASE
    Error:
      type: object
      required:
        - code
        - messages
        - httpCode
      properties:
        code:
          type: string
          description: Código de error estable.
          enum:
            - NOT_AUTHENTICATED
            - AuthenticationFail
            - INVALID_PARAMETERS
            - TRAFFIC_LOG_VALIDATION_FAILED
            - TRAFFIC_LOG_MERCHANT_REFERENCE_REQUIRED
            - TRAFFIC_LOG_BODY_ENCODING_MISMATCH
            - TRAFFIC_LOG_IDEMPOTENCY_REPLAY
            - TRAFFIC_LOG_PAYLOAD_TOO_LARGE
            - TRAFFIC_LOG_UNSUPPORTED_CONTENT_TYPE
            - TRAFFIC_LOG_SEMANTIC_INVALID
            - PAYMENT_NOT_FOUND
            - RATE_LIMITED
        messages:
          type: array
          items:
            type: string
          description: Detalles del error legibles para personas.
        httpCode:
          type: integer
          format: int32
    Event:
      type: object
      required:
        - type
        - http_method
        - operation_type
        - headers
      properties:
        type:
          type: string
          enum:
            - REQUEST
            - RESPONSE
            - WEBHOOK
          description: Qué tramo del intercambio captura esta entrada.
          example: REQUEST
        http_method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          example: POST
        operation_type:
          type: string
          enum:
            - PURCHASE
            - AUTHORIZE
            - CAPTURE
            - CANCEL
            - REFUND
            - CHARGEBACK
            - THREE_D_SECURE
          description: Identifica el tipo de operación de pago que se simula.
          example: PURCHASE
        base_url:
          type: string
          format: uri
          description: >-
            Obligatorio para REQUEST y WEBHOOK. Origen del endpoint del
            proveedor: esquema + host + puerto (por ejemplo,
            https://api.stripe.com).
          example: https://api.stripe.com
        endpoint:
          type: string
          description: >-
            Obligatorio para REQUEST y WEBHOOK. Parte de la ruta y la consulta
            (por ejemplo, /v1/charges?expand=customer).
          example: /v1/charges
        http_status_code:
          type: integer
          format: int32
          minimum: 100
          maximum: 599
          description: Obligatorio para RESPONSE y WEBHOOK. Omítelo para REQUEST.
        headers:
          type: string
          format: byte
          maxLength: 87400
          description: >
            Payload de encabezados codificado en Base64. El contenido
            decodificado puede ser un mapa

            `{header-name: header-value}` serializado en JSON o el bloque de
            encabezados HTTP sin procesar. Límite

            estricto: 64 KB de bytes decodificados por evento.
          example: eyBDb250ZW50LVR5cGU6IGFwcGxpY2F0aW9uL2pzb24gfQ==
        body:
          type: string
          format: byte
          maxLength: 1398000
          description: >
            Payload del cuerpo codificado en Base64. Omítelo para cuerpos
            vacíos. Límite estricto: 1 MB de

            bytes decodificados por evento. Para cuerpos que no son UTF-8
            (protobuf, gzip),

            codifica en Base64 directamente los bytes sin procesar.
          example: eyBhbW91bnQ6IDIwMDAsIGN1cnJlbmN5OiAidXNkIiB9

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.