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

# Reportar transacciones fuera de Yuno

> Reporta las transacciones procesadas directamente con tus proveedores para que aparezcan en Yuno como pagos: dashboard, listados y analíticas incluidos.

Este endpoint le da a Yuno visibilidad sobre el tráfico que procesas **directamente con tus proveedores**, fuera de la ruta de transacciones de Yuno. Cada evento aceptado se guarda como un **pago normal de Yuno**, diferenciado por el campo `origin`:

* `origin: YUNO`: pagos procesados por Yuno (todos los pagos existentes).
* `origin: REPORTED`: pagos que ingresaron a través de esta API.

Los pagos reportados aparecen en el dashboard, en `GET /v1/payments` y en las analíticas (filtrados por `origin`), pero Yuno **nunca los procesa**: sin enrutamiento, sin llamadas a proveedores, sin reintentos y sin movimiento de dinero. El dinero ya se movió en tu proveedor; Yuno registra el hecho.

> [!NOTE]
>
> **Habilitado por organización**
>
> Esta API requiere activación para tu organización. Contacta a tu Key Account Manager (KAM) para habilitarla.

## Cómo funciona

1. Procesas una transacción directamente con tu proveedor (por ejemplo, una compra en tu propia cuenta de Adyen).
2. La reportas aquí: un evento o un lote de hasta 500. Para integraciones sensibles a la latencia, se recomiendan lotes de hasta 100 eventos. El lote completo de 500 eventos se procesa de forma síncrona y puede tardar varios segundos.
3. Cada evento aceptado crea **un pago** con una transacción, con el estado derivado de `result` y del tipo de evento:
   * Un `PURCHASE` con resultado `SUCCEEDED` deja el pago en `SUCCEEDED`.
   * Un `AUTHORIZE` con resultado `SUCCEEDED` queda en `PENDING` con subestado `AUTHORIZED`. Una autorización aprobada no es dinero capturado; refleja cómo se comportan las autorizaciones procesadas por Yuno.
   * Un `VERIFY` con resultado `SUCCEEDED` queda en `SUCCEEDED` con subestado `VERIFIED`. La verificación se completó y no se mueve dinero; refleja cómo se guardan las verificaciones procesadas por Yuno.
   * `DECLINED` queda en `DECLINED`, y `ERROR` queda en `ERROR`.

En esta versión, las operaciones admitidas son `PURCHASE` (predeterminada), `AUTHORIZE` y `VERIFY`. Un `VERIFY` reporta una verificación de tarjeta (autorización de cero dólares), que normalmente se reporta con `amount.value: 0`. Los eventos del ciclo de vida (capturas, reembolsos, contracargos) están en la hoja de ruta.

## Reintentos y deduplicación

**No hay encabezado de idempotencia en este endpoint, ni se necesita.** El `report_id` que generas por evento es la clave de deduplicación. Un evento cuyo `report_id` ya fue ingerido se cuenta en `duplicates` y nunca se ingiere dos veces, sin importar cuándo ni en qué lote llegue. Reintentar un lote completo después de una falla de red siempre es seguro.

Como solo el `report_id` decide, un evento que reutiliza un `report_id` ya ingerido con un payload *distinto* también se cuenta como duplicado y se descarta en silencio: nunca reutilices un `report_id` en transacciones diferentes.

El lote se procesa **por evento**: un evento inválido queda en `rejected[]` con su motivo, y el resto del lote no se ve afectado.

## BIN de la tarjeta para estadísticas de enrutamiento por BIN

En los eventos `CARD` puedes enviar el BIN de la tarjeta en `payment_method_details.card.bin`: exactamente los primeros **6 u 8 dígitos** del número de la tarjeta. El BIN no es dato del titular de la tarjeta: identifica al emisor y el rango de la tarjeta, nunca la tarjeta.

Cuando está presente, Yuno lo guarda en el pago reportado (`payment_method.detail.card.card_data.iin` en la transacción) y lo usa para segmentar tus estadísticas por BIN en la [API de recomendaciones de enrutamiento](https://docs.y.uno/es/reference/organizations/routing/get-routing-recommendations.md), de modo que un pago con el mismo BIN se pueda clasificar según el historial propio de ese BIN en lugar del de todo el país.

* `payment_method_details` se identifica por el tipo de método de pago: hoy solo `card`, y solo en eventos cuyo `payment_method_type` es `CARD`. Un `card.bin` en un evento de cualquier otro tipo, o un contenedor con cualquier otra clave, rechaza el evento.
* El BIN debe tener exactamente 6 u 8 dígitos. Un valor de 7 dígitos, un valor más largo o cualquier cosa que no sean solo dígitos rechaza el evento con `INVALID_EVENT`.
* Omitir `payment_method_details`, o enviarlo vacío (`{}` o `{"card": {}}`), deja el evento exactamente como antes: no se guarda ningún BIN y el evento alimenta solo las estadísticas de país y método de pago.

## Iniciación CIT / MIT para estadísticas de enrutamiento por iniciación

Puedes indicarle a Yuno cómo se inició cada transacción enviando `initiation` a nivel de evento: `CIT` (iniciada por el titular de la tarjeta: el cliente estaba presente en el checkout) o `MIT` (iniciada por el comercio, por ejemplo la renovación de una suscripción). CIT y MIT se aprueban de forma muy distinta según el proveedor, por lo que dividir tu historial reportado por iniciación permite que la [API de recomendaciones de enrutamiento](https://docs.y.uno/es/reference/organizations/routing/get-routing-recommendations.md) clasifique un pago según el historial de su propio tipo de iniciación.

* `initiation` es opcional y va al nivel plano del evento, igual que `token_type_used`. Solo acepta `CIT` o `MIT`; cualquier otro valor rechaza ese evento con `INVALID_EVENT` y el mensaje `The field 'initiation' must be CIT or MIT.`
* Omitir `initiation` deja el evento exactamente como antes: alimenta solo las estadísticas sin iniciación, y una solicitud de recomendación que no lleva `payment.initiation` no se ve afectada.

## ID de recomendación para la atribución de resultados

Si enrutas con la [API de recomendaciones de enrutamiento](https://docs.y.uno/es/reference/organizations/routing/get-routing-recommendations.md), envía el `recommendation_id` que devolvió para el pago en el evento que reportas. Yuno lo usa para atribuir el resultado reportado a la recomendación exacta, en lugar de hacer la coincidencia por `merchant_order_id`.

* `recommendation_id` es opcional y va al nivel plano del evento, igual que `initiation`. Envíalo exactamente como se devolvió: un UUID v4 en minúsculas. Cualquier otro valor, incluida una cadena vacía, rechaza ese evento con `INVALID_EVENT` y el mensaje `The field 'recommendation_id' must be a UUID.`
* Yuno solo verifica el formato. No comprueba que la recomendación exista ni que pertenezca a tu cuenta, por lo que un valor desconocido se guarda pero no atribuye nada.
* Envíalo con el primer reporte del evento. Volver a enviar un `report_id` que ya fue ingerido cuenta como duplicado y no agrega ni cambia el `recommendation_id`.
* Omitir `recommendation_id`, o enviar `null`, deja el evento exactamente como antes.

## La respuesta sin procesar del proveedor

Si incluyes `raw_provider_response` (el payload de respuesta del proveedor, textual, de hasta 64 KB), Yuno lo guarda aplicando una redacción defensiva de datos de tarjeta: los números de cuenta principales y los códigos de seguridad se eliminan antes de guardar nada. Ninguna API lo devuelve nunca.

Se recomienda enviarlo: permite que Yuno enriquezca el pago reportado más adelante (referencias de transacción de la red, motivos de rechazo) sin pedirte nada nuevo.

> [!WARNING]
>
> **Nunca envíes datos de tarjeta en los campos del evento.** Los eventos reportados llevan referencias y resultados, no datos del titular de la tarjeta. El BIN en `payment_method_details.card.bin` es el único valor derivado de la tarjeta que se acepta, y no es un número de tarjeta. El único lugar por donde puede pasar un número de tarjeta es dentro de `raw_provider_response`, donde se redacta al ingerirse.

## Operaciones sobre pagos reportados

Los pagos reportados no se pueden operar a través de Yuno: una solicitud de reembolso o de captura sobre un pago con `origin: REPORTED` devuelve `403 OPERATION_NOT_ALLOWED_FOR_REPORTED_PAYMENT`. Realiza la operación en tu proveedor y repórtala como un evento nuevo cuando los eventos del ciclo de vida estén disponibles.

## Errores

Los errores devuelven un `code` y un arreglo `messages`.

| HTTP | `code` | Cuándo |
| - | - | - |
| 400 | `INVALID_REQUEST` | Cuerpo mal formado, falta un campo obligatorio o un lote de más de 500 eventos. |
| 400 | `INVALID_ACCOUNT_ID` | El `account_id` no existe o no pertenece a tu organización. |
| 401 | `NOT_AUTHENTICATED` / `INVALID_CREDENTIALS` | Faltan los encabezados `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` o no son válidos. |
| 403 | `PRODUCT_NOT_ENABLED` | "La API Transaction Reporting está habilitada por organización. Contacta a tu gerente de cuenta clave (KAM) para activarla." |

### Rechazos por evento: `INVALID_EVENT`

`INVALID_EVENT` no es un error HTTP: el lote en sí se acepta (`202`), y cada evento inválido se devuelve individualmente dentro de `rejected[]` con este código y su motivo, mientras el resto del lote se ingiere con normalidad:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "accepted": 2,
  "duplicates": 0,
  "rejected": [
    { "report_id": "merchant-rpt-000124", "code": "INVALID_EVENT", "messages": ["The field 'event_type' must be one of: PURCHASE, AUTHORIZE, VERIFY."] }
  ]
}
```

Causas: valor de enum inválido, tipo de campo incorrecto, campo desconocido, un `payment_method_details.card.bin` que no tiene exactamente 6 u 8 dígitos (o que se envía en un evento que no es `CARD`), o `raw_provider_response` de más de 64 KB.


## OpenAPI

````yaml openapi/es/reporting/report-transactions.json POST /reporting/transactions
openapi: 3.1.0
info:
  title: Yuno Transaction Reporting 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:
  /reporting/transactions:
    post:
      summary: Reportar transacciones fuera de Yuno
      description: >-
        Reporta transacciones procesadas directamente con un proveedor (fuera de
        Yuno). Cada evento aceptado se guarda como un pago normal de Yuno con
        `origin: REPORTED`: es visible en el Dashboard, los listados y las
        analíticas, pero Yuno nunca lo enruta, reintenta ni cobra.
      operationId: report-transactions
      parameters:
        - in: header
          name: PUBLIC-API-KEY
          schema:
            type: string
          description: Tu clave de API pública.
        - in: header
          name: PRIVATE-SECRET-KEY
          schema:
            type: string
          description: Tu clave secreta privada. Nunca la expongas del lado del cliente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - events
              properties:
                account_id:
                  type: string
                  format: uuid
                  description: >-
                    UUID de la cuenta de Yuno a la que pertenecen los pagos
                    reportados.
                events:
                  type: array
                  minItems: 1
                  maxItems: 500
                  description: >-
                    Un evento o un lote de hasta 500. Los eventos se procesan
                    por elemento: un evento no válido nunca rechaza el lote.
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - report_id
                      - merchant_order_id
                      - country
                      - payment_method_type
                      - result
                      - amount
                      - provider_id
                    properties:
                      report_id:
                        type: string
                        maxLength: 255
                        description: >-
                          Tu identificador único para este evento, la clave de
                          deduplicación. Un evento con un `report_id` ya
                          ingerido se cuenta como duplicado y nunca se ingiere
                          dos veces, lo que hace seguros los reintentos.
                        examples:
                          - merchant-rpt-000123
                      merchant_order_id:
                        type: string
                        maxLength: 255
                        description: >-
                          Tu referencia de orden, que te permite encontrar el
                          pago en el Dashboard.
                        examples:
                          - order_45678
                      country:
                        type: string
                        minLength: 2
                        maxLength: 2
                        description: >-
                          Código de país ISO 3166-1 alpha-2 de la transacción,
                          en mayúsculas (por ejemplo, `US`); los códigos en
                          minúsculas o desconocidos se rechazan.
                        examples:
                          - US
                      payment_method_type:
                        type: string
                        description: >-
                          Tipo de método de pago usado en el proveedor: debe ser
                          uno de los tipos de método de pago de Yuno (por
                          ejemplo, `CARD`, `PIX`); los tipos desconocidos se
                          rechazan.
                        examples:
                          - CARD
                      result:
                        type: string
                        enum:
                          - SUCCEEDED
                          - DECLINED
                          - ERROR
                        description: >-
                          El resultado que te dio el proveedor. Se asigna al
                          estado del pago junto con el tipo de evento:
                          `PURCHASE`+`SUCCEEDED` → pago `SUCCEEDED`;
                          `AUTHORIZE`+`SUCCEEDED` → `PENDING`/`AUTHORIZED` (una
                          autorización aprobada no es dinero capturado);
                          `DECLINED` → `DECLINED`; `ERROR` → `ERROR`.
                      amount:
                        type: object
                        required:
                          - value
                          - currency
                        description: >-
                          Monto de la transacción. Valor decimal: un pago de $99
                          es `99.00`, no `9900`.
                        properties:
                          value:
                            type: number
                            minimum: 0
                            description: >-
                              Monto decimal, mayor o igual que cero. Un monto de
                              `0` es típico de los eventos `VERIFY`
                              (verificación de cero dólares).
                            examples:
                              - 99
                          currency:
                            type: string
                            minLength: 3
                            maxLength: 3
                            description: >-
                              Código de moneda ISO 4217 en mayúsculas (por
                              ejemplo, `USD`); los códigos en minúsculas o
                              desconocidos se rechazan.
                            examples:
                              - USD
                      provider_id:
                        type: string
                        description: >-
                          El proveedor con el que procesaste la transacción:
                          debe ser uno de los ID de proveedor del catálogo de
                          Yuno (por ejemplo, `ADYEN`); los proveedores
                          desconocidos se rechazan. Se muestra en el pago y
                          permite la segmentación por proveedor en el Dashboard
                          y las analíticas.
                        examples:
                          - ADYEN
                      latency_ms:
                        type: integer
                        minimum: 0
                        description: >-
                          Opcional. El tiempo de respuesta del proveedor
                          observado por ti, en milisegundos (ida y vuelta de la
                          llamada de autorización). Alimenta las analíticas de
                          latencia por proveedor y los objetivos LATENCY y
                          BALANCED de las Routing Recommendations: los eventos
                          sin este dato no aportan latencia para clasificar.
                        examples:
                          - 180
                      token_type_used:
                        type: string
                        enum:
                          - FPAN
                          - DPAN
                          - PROVIDER_TOKEN
                        description: >-
                          Opcional. La credencial que enviaste al proveedor para
                          esta transacción: `FPAN`, el número real de la tarjeta
                          (funding PAN); `DPAN`, el token de red de la tarjeta;
                          `PROVIDER_TOKEN`, un token emitido por ese proveedor
                          para la tarjeta almacenada (por ejemplo, un token de
                          tarjeta guardada o de método de pago almacenado en el
                          vault propio del proveedor). Habilita el análisis de
                          la tasa de aprobación por tipo de token.
                        examples:
                          - DPAN
                      initiation:
                        type: string
                        enum:
                          - CIT
                          - MIT
                        description: >-
                          Opcional. Cómo se inició la transacción en el
                          proveedor: `CIT`, iniciada por el titular de la
                          tarjeta (el cliente estaba presente en el checkout);
                          `MIT`, iniciada por el comercio (por ejemplo, la
                          renovación de una suscripción). Cualquier otro valor
                          rechaza el evento con `INVALID_EVENT` y el mensaje
                          "The field 'initiation' must be CIT or MIT." Habilita
                          las estadísticas de tasa de aprobación divididas por
                          iniciación en las Routing Recommendations. Omítelo
                          para dejar el evento exactamente como antes.
                        examples:
                          - MIT
                      recommendation_id:
                        type: string
                        format: uuid
                        description: >-
                          Opcional. El `recommendation_id` devuelto por `POST
                          /v1/routing/recommendations` para este pago, para que
                          Yuno pueda atribuir el resultado reportado a esa
                          recomendación. Debe ser el valor exactamente como se
                          devolvió: un UUID v4 en minúsculas. No se valida
                          contra las recomendaciones existentes. Cualquier otro
                          valor rechaza el evento con `INVALID_EVENT` y el
                          mensaje "The field 'recommendation_id' must be a
                          UUID." Omítelo (o envía `null`) para dejar el evento
                          exactamente como antes.
                        examples:
                          - 3f9c2a7e-1b7d-4c2a-9a1e-6e1f0c2b9d11
                      payment_method_details:
                        type: object
                        additionalProperties: false
                        description: >-
                          Opcional. Detalles del método de pago usado en el
                          proveedor, indexados por el tipo de método de pago:
                          hoy solo `card`, y solo en eventos cuyo
                          `payment_method_type` es `CARD`. Un `card.bin` en un
                          evento de otro tipo, o un contenedor con cualquier
                          otra clave, rechaza el evento. Un contenedor vacío
                          (`{}` o `{"card": {}}`) se trata como ausente.
                        properties:
                          card:
                            type: object
                            additionalProperties: false
                            properties:
                              bin:
                                type: string
                                pattern: ^([0-9]{6}|[0-9]{8})$
                                description: >-
                                  El BIN de la tarjeta: exactamente los primeros
                                  6 u 8 dígitos del número de la tarjeta;
                                  cualquier otra longitud o un carácter que no
                                  sea un dígito rechaza el evento con
                                  `INVALID_EVENT`. No son datos del titular de
                                  la tarjeta. Se almacena en la transacción del
                                  pago reportado como
                                  `payment_method.detail.card.card_data.iin` y
                                  se usa para construir estadísticas a nivel de
                                  BIN para las Routing Recommendations. Omítelo
                                  para dejar el evento exactamente como antes.
                                examples:
                                  - '45717360'
                      event_type:
                        type: string
                        enum:
                          - PURCHASE
                          - AUTHORIZE
                          - VERIFY
                        default: PURCHASE
                        description: >-
                          Opcional. La operación que realizaste en el proveedor:
                          `PURCHASE`, un cargo directo (autorización y captura
                          en un solo paso; es el valor predeterminado cuando se
                          omite); `AUTHORIZE`, una autorización que se capturará
                          más tarde (el pago queda `PENDING` con el subestado
                          `AUTHORIZED`); `VERIFY`, una verificación de tarjeta o
                          autorización de cero dólares (el pago queda
                          `SUCCEEDED` con el subestado `VERIFIED`).
                      occurred_at:
                        type: string
                        format: date-time
                        description: >-
                          Opcional. Cuándo ocurrió la transacción en el
                          proveedor (RFC 3339, UTC). Por defecto, es el momento
                          en que Yuno recibe el evento.
                        examples:
                          - '2026-08-14T10:41:07Z'
                      raw_provider_response:
                        type: object
                        description: >-
                          Opcional. La carga útil de respuesta del proveedor,
                          tal cual (JSON, hasta 64 KB). Se almacena con una
                          redacción defensiva de datos de tarjeta aplicada;
                          ninguna API la devuelve nunca. Archivarla permite que
                          Yuno enriquezca el pago más adelante sin pedirte nada
                          nuevo.
            examples:
              minimal:
                summary: Minimal event (required fields only)
                value:
                  account_id: 3f2a1b6c-8d4e-4f5a-9b0c-1d2e3f4a5b6c
                  events:
                    - report_id: merchant-rpt-000123
                      merchant_order_id: order_45678
                      country: US
                      payment_method_type: CARD
                      result: SUCCEEDED
                      amount:
                        currency: USD
                        value: 99
                      provider_id: ADYEN
              full:
                summary: Full event (all v1 fields)
                value:
                  account_id: 3f2a1b6c-8d4e-4f5a-9b0c-1d2e3f4a5b6c
                  events:
                    - report_id: merchant-rpt-000125
                      merchant_order_id: order_45679
                      country: US
                      payment_method_type: CARD
                      result: SUCCEEDED
                      amount:
                        currency: USD
                        value: 99
                      provider_id: ADYEN
                      latency_ms: 180
                      token_type_used: DPAN
                      initiation: MIT
                      recommendation_id: 3f9c2a7e-1b7d-4c2a-9a1e-6e1f0c2b9d11
                      payment_method_details:
                        card:
                          bin: '45717360'
                      event_type: PURCHASE
                      occurred_at: '2026-08-14T10:41:07Z'
                      raw_provider_response:
                        pspReference: '8815992887'
                        resultCode: Authorised
      responses:
        '202':
          description: Lote aceptado y procesado por evento.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: integer
                    description: Eventos ingeridos como pagos.
                  duplicates:
                    type: integer
                    description: >-
                      Eventos omitidos porque su `report_id` ya se había
                      ingerido.
                  rejected:
                    type: array
                    description: >-
                      Eventos que no pasaron la validación, cada uno con su
                      motivo. El resto del lote no se ve afectado.
                    items:
                      type: object
                      properties:
                        report_id:
                          type: string
                        code:
                          type: string
                          examples:
                            - INVALID_EVENT
                        messages:
                          type: array
                          items:
                            type: string
              examples:
                mixed:
                  value:
                    accepted: 2
                    duplicates: 1
                    rejected:
                      - report_id: merchant-rpt-000124
                        code: INVALID_EVENT
                        messages:
                          - >-
                            The field 'event_type' must be one of: PURCHASE,
                            AUTHORIZE, VERIFY.
        '400':
          description: >-
            Fallo de validación a nivel de solicitud: cuerpo mal formado, falta
            un campo obligatorio o un lote de más de 500 eventos. Un
            `account_id` que no existe o no pertenece a tu organización responde
            `INVALID_ACCOUNT_ID`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                invalid_request:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - >-
                        The field 'events' must contain between 1 and 500
                        events.
        '401':
          description: >-
            No autorizado: `NOT_AUTHENTICATED` / `INVALID_CREDENTIALS` (faltan
            los encabezados `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` o no son
            válidos).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                not_authenticated:
                  value:
                    code: NOT_AUTHENTICATED
                    messages:
                      - >-
                        Missing or invalid PUBLIC-API-KEY / PRIVATE-SECRET-KEY
                        headers.
        '403':
          description: >-
            Prohibido: `PRODUCT_NOT_ENABLED` (el producto no está habilitado
            para tu organización).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                product_not_enabled:
                  value:
                    code: PRODUCT_NOT_ENABLED
                    messages:
                      - >-
                        The Transaction Reporting API is enabled per
                        organization. Contact your Key Account Manager (KAM) to
                        activate it.

````

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