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

# Generar criptograma de network token

> Genera un criptograma de network token nuevo y de un solo uso para una tarjeta almacenada en el vault, de modo que pueda autorizarse en un PSP externo.

Este endpoint devuelve, bajo demanda, un **criptograma de network token** para una tarjeta almacenada en el vault y, por defecto, el network token vigente de la tarjeta (DPAN). El network token de una tarjeta no basta por sí solo para autorizar un pago. Las marcas de tarjeta exigen un criptograma de un solo uso por transacción, y solo Yuno puede solicitarlo porque Yuno posee el Token Requestor ID. Usa este endpoint cuando quieras tomar un network token de Yuno y autorizar la transacción en tu propio PSP.

Identificas la tarjeta con su `vaulted_token`, el mismo identificador que usas en [Create Payment](https://docs.y.uno/es/reference/payments/create-payment.md). Yuno resuelve internamente el network token vigente de la tarjeta y absorbe la rotación de tokens, de modo que siempre recibes un conjunto `(DPAN, cryptogram, ECI)` consistente y vigente.

> [!WARNING]
>
> **El DPAN requiere certificación PCI: el criptograma no**
>
> El network token completo (DPAN) equivale a datos de PAN, por lo que la respuesta por defecto, que lo incluye, solo está disponible para comercios con certificación PCI. El criptograma en sí no equivale a datos de PAN: es de un solo uso, de corta duración y está vinculado a un DPAN específico, por lo que no puede autorizar nada por sí solo.
>
> Si tu organización no tiene certificación PCI, envía `include_network_token: false` para recibir solo el criptograma. Consulta [Modo solo criptograma](#cryptogram-only-mode) más abajo. Para habilitar el producto, comunícate con tu Key Account Manager (KAM).

> [!WARNING]
>
> **Envía siempre un par consistente.** Un criptograma está vinculado a un network token específico. Envía el `network_token.number` (DPAN) devuelto en la **misma respuesta** junto con su `cryptogram` y su `eci`. Nunca combines un criptograma devuelto con un DPAN almacenado previamente. Después de una rotación de token, un DPAN almacenado dejará de coincidir. En el [modo solo criptograma](#cryptogram-only-mode) se aplica la misma regla a través del proxy: reenvía inmediatamente después de solicitar el criptograma, para que el DPAN que resuelve el proxy sea aquel para el que se generó el criptograma.

## Cómo funciona

1. Solicita un criptograma justo antes de autorizar. Cada llamada genera un criptograma **nuevo y de un solo uso** desde la marca: no hay idempotencia, y las llamadas duplicadas devuelven criptogramas nuevos (no se mueve dinero).
2. Envía `network_token.number` (DPAN), `cryptogram` y `eci` a tu PSP como una transacción con network token.
3. Si la autorización es rechazada y reintentas, solicita primero un criptograma **nuevo**. Un criptograma usado o vencido no puede reutilizarse.

## Modo solo criptograma

Envía `include_network_token: false` y la respuesta omite por completo `network_token.number` (el DPAN) y `network_token.token_data`. El objeto `network_token` conserva sus metadatos que no equivalen a datos de PAN (`network`, `status`, `par`, `network_token_id`), y la respuesta incluye `cryptogram` y `eci` como de costumbre. Como no se devuelven datos equivalentes a PAN, este modo no requiere certificación PCI.

Combínalo con el [Forward Proxy](https://docs.y.uno/es/docs/security-and-compliance/pci-proxy/forward-proxy.md) para ejecutar una transacción con network token de extremo a extremo sin que datos equivalentes a PAN entren en tus sistemas:

1. Solicita el criptograma con `include_network_token: false`.
2. Construye la solicitud de reenvío con la expresión `{{vaulted_token.<TOKEN>.network_token_number}}` (y las expresiones `network_token_expiration_*`) donde el destino espera el DPAN. Incluye el valor de `cryptogram` directamente en el cuerpo, ya que los criptogramas se generan por transacción y el proxy no los resuelve como expresiones.
3. Envíala a través del proxy **de inmediato**: el proxy resuelve el DPAN vigente de la tarjeta en el momento del reenvío, y el criptograma está vinculado a un DPAN específico. Solicitar el criptograma justo antes del reenvío mantiene el par consistente. Una demora que abarque una rotación de token provocaría que no coincidan.

La matriz completa de condiciones:

| Tu organización | `include_network_token` | Resultado |
| - | - | - |
| Con certificación PCI | `true` / omitido | Respuesta completa (network token + criptograma) |
| Con certificación PCI | `false` | Respuesta solo con criptograma |
| Sin certificación PCI | `false` | Respuesta solo con criptograma |
| Sin certificación PCI | `true` / omitido | `403 NETWORK_TOKEN_RETURN_NOT_ALLOWED` |

La última fila es un error explícito por diseño: un integrador que espera `network_token` en la respuesta recibe un rechazo claro, nunca una respuesta con una forma degradada en silencio.

## Requisitos

Para usar este endpoint, tu organización debe:

* Tener el **producto habilitado** para tu organización.
* Estar **incorporada a network tokens** para la marca de la tarjeta y el `country` solicitado.
* Ser un **comercio con certificación PCI** para recibir el network token (DPAN) en la respuesta. El [modo solo criptograma](#cryptogram-only-mode) (`include_network_token: false`) no requiere certificación PCI.

La tarjeta a la que hace referencia `vaulted_token` debe ser una **tarjeta inscrita** de tu organización que ya tenga un **network token activo**.

Redes compatibles: **Visa** y **Mastercard**.

> [!NOTE]
>
> **Cuándo no necesitas este endpoint.** Las transacciones recurrentes iniciadas por el comercio (MIT) se autorizan con el network token y el `network_transaction_id` almacenado, y **no** requieren un criptograma. Este endpoint es para transacciones iniciadas por el cliente que necesitan un criptograma nuevo.

## Vigencia del criptograma

El criptograma es de un solo uso. Solicítalo inmediatamente antes de autorizar y no lo guardes en caché.

`expires_at` es el último momento en el que la marca acepta el criptograma. Es la vigencia del **criptograma**, no la del network token ni la de la tarjeta.

* **Una marca de tiempo** (hoy, Mastercard): trátala como un límite estricto. Un criptograma enviado después de `expires_at` es rechazado.
* **`null`** (hoy, Visa): la red no publica vigencia para este criptograma. Esto no significa que nunca venza. Úsalo de inmediato.

En ambos casos, solicita un criptograma nuevo para cada intento de autorización, incluidos los reintentos.

## Errores

Los errores devuelven un `code` y un arreglo `messages`. El valor exacto de `messages` por cada `code`:

| HTTP | `code` | `messages` |
| - | - | - |
| 404 | `PAYMENT_METHOD_NOT_FOUND` | "Payment method not found." |
| 400 | `INSTRUMENT_NOT_TOKENIZABLE` | "Payment method is not a card." |
| 400 | `PAYMENT_METHOD_NOT_ENROLLED` | "Payment method is not enrolled." |
| 400 | `NETWORK_TOKEN_NOT_FOUND` | "Payment method has no network token." |
| 400 | `TOKEN_NOT_ACTIVE` | "Network token is not active." |
| 400 | `NETWORK_NOT_SUPPORTED` | "Network token brand is not supported." |
| 400 | `COUNTRY_NOT_SUPPORTED` | "Country is not supported for this organization." |
| 400 | `INVALID_REQUEST` | El campo inválido específico, por ejemplo "The field 'vaulted\_token' must be a valid uuid v4." |
| 403 | `PCI_MERCHANT_REQUIRED` | "This endpoint is only available to PCI-certified merchants." |
| 403 | `NETWORK_TOKEN_RETURN_NOT_ALLOWED` | "Returning the network token requires PCI certification. Send include\_network\_token: false to receive the cryptogram only, or contact your Key Account Manager (KAM)." |
| 403 | `PRODUCT_NOT_ENABLED` | "The Network Token Cryptogram API is enabled per organization. Contact your Key Account Manager (KAM) to activate it." |
| 502 | `PROVIDER_ERROR` | "The network token cryptogram service is temporarily unavailable, please retry." |

Un `vaulted_token` que no existe y uno que pertenece a otra organización devuelven el mismo `PAYMENT_METHOD_NOT_FOUND`, por lo que no hay filtración de existencia.


## OpenAPI

````yaml openapi/es/network-tokens/generate-network-token-cryptogram.json POST /network-tokens/cryptograms
openapi: 3.1.0
info:
  title: network-token-cryptogram
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /network-tokens/cryptograms:
    post:
      summary: Generar criptograma de token de red
      description: >-
        Genera un criptograma de token de red nuevo y de un solo uso para una
        tarjeta almacenada en el vault, de modo que pueda autorizarse en un PSP
        externo. Por defecto, la respuesta también incluye el token de red
        actual de la tarjeta (DPAN), lo que requiere certificación PCI; con
        `include_network_token: false` la respuesta contiene solo el criptograma
        y no lo requiere.
      operationId: generate-network-token-cryptogram
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vaulted_token
                - country
              properties:
                vaulted_token:
                  type: string
                  format: uuid
                  description: >-
                    El token en el vault de la tarjeta, el mismo identificador
                    que se usa como `payment_method.vaulted_token` en [Create
                    Payment](https://docs.y.uno/es/reference/payments/create-payment).
                    La tarjeta debe ser una tarjeta inscrita de tu organización
                    con un token de red activo.
                  examples:
                    - 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                country:
                  type: string
                  description: >-
                    Código de país ISO 3166-1 alpha-2 donde se usará el token.
                    Resuelve el onboarding del token de red (organización +
                    marca + país), con la misma semántica que `country` en
                    Create Payment.
                  examples:
                    - US
                amount:
                  type: object
                  description: >-
                    Opcional. Se reenvía a la red; se recomienda, ya que algunos
                    flujos de la red vinculan el monto.
                  properties:
                    currency:
                      type: string
                      description: Código de moneda ISO 4217.
                      examples:
                        - USD
                    value:
                      type: number
                      description: Valor del monto en la moneda indicada.
                      examples:
                        - 49.99
                include_network_token:
                  type: boolean
                  default: true
                  description: >-
                    Opcional. Indica si la respuesta incluye las partes
                    equivalentes al PAN del token de red: `network_token.number`
                    (el DPAN) y `network_token.token_data`. Por defecto es
                    `true`, lo que requiere que tu organización sea un comercio
                    con certificación PCI. Envía `false` para obtener una
                    respuesta con solo el criptograma y sin datos equivalentes
                    al PAN (el objeto `network_token` conserva `network`,
                    `status`, `par` y `network_token_id`): está disponible sin
                    certificación PCI y está diseñado para usarse junto con el
                    [Forward
                    Proxy](https://docs.y.uno/es/docs/security-and-compliance/pci-proxy/forward-proxy),
                    que resuelve el DPAN en el momento del reenvío mediante la
                    expresión `network_token_number`. Una organización sin
                    certificación PCI que envíe `true` u omita el campo recibe
                    `403 NETWORK_TOKEN_RETURN_NOT_ALLOWED`.
                  examples:
                    - false
            examples:
              cryptogram_only:
                summary: Cryptogram-only (no PCI certification required)
                value:
                  vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                  country: US
                  amount:
                    currency: USD
                    value: 49.99
                  include_network_token: false
              default:
                summary: With the network token (PCI certification required)
                value:
                  vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                  country: US
                  amount:
                    currency: USD
                    value: 49.99
                  include_network_token: true
      responses:
        '201':
          description: Criptograma generado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vaulted_token:
                    type: string
                    description: Eco del token en el vault de la solicitud.
                  network_token:
                    type: object
                    description: >-
                      El token de red actual de la tarjeta. Mismo formato que
                      devuelve la recuperación de token de red PCI. **Cuando la
                      solicitud establece `include_network_token: false`, los
                      campos `number` (DPAN) y `token_data` se omiten por
                      completo**: el objeto conserva `network`, `status`, `par`
                      y `network_token_id`.
                    properties:
                      network:
                        type: string
                        description: Red de la tarjeta.
                        examples:
                          - VISA
                      number:
                        type: string
                        description: >-
                          El DPAN actual (PAN del dispositivo o de la red).
                          **Envía siempre este valor junto con el `cryptogram`
                          devuelto**, nunca un DPAN almacenado previamente.
                        examples:
                          - '4111111111111111'
                      status:
                        type:
                          - string
                          - 'null'
                        description: Estado del token de red.
                        examples:
                          - ACTIVE
                      par:
                        type:
                          - string
                          - 'null'
                        description: Payment Account Reference.
                      network_token_id:
                        type:
                          - string
                          - 'null'
                        description: Identificador del token de red.
                      token_data:
                        type: object
                        properties:
                          iin:
                            type: string
                          lfd:
                            type: string
                            description: Últimos cuatro dígitos del DPAN.
                          expiration_month:
                            type: integer
                            examples:
                              - 7
                          expiration_year:
                            type: integer
                            examples:
                              - 2029
                  cryptogram:
                    type: string
                    description: >-
                      Un criptograma nuevo y de un solo uso de la red, generado
                      en cada llamada. Envíalo junto con `network_token.number`
                      (DPAN) y `eci` a tu PSP.
                    examples:
                      - AgAAAAAABk4DWZ4C28yUQAAAAAA=
                  eci:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Electronic Commerce Indicator. Puede ser `null` en algunos
                      formatos DSRP de Mastercard.
                    examples:
                      - '05'
                  created_at:
                    type: string
                    format: date-time
                    description: Marca de tiempo de emisión (UTC).
                  expires_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: >-
                      Último momento (UTC) en el que la red acepta este
                      criptograma. Es la vigencia del criptograma, no la del
                      token de red ni la de la tarjeta. `null` cuando la red no
                      publica vigencia para el criptograma (hoy, Visa). En
                      cualquier caso, solicita un criptograma nuevo para cada
                      intento de autorización y no lo guardes en caché.
                    examples:
                      - '2026-07-21T14:32:10Z'
              examples:
                default:
                  summary: Visa, with the network token (PCI certification required)
                  value:
                    vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                    network_token:
                      network: VISA
                      number: '4111111111111111'
                      status: ACTIVE
                      par: V0010013022280191
                      network_token_id: DNITHE302344816910968
                      token_data:
                        iin: '411111'
                        lfd: '1111'
                        expiration_month: 7
                        expiration_year: 2029
                    cryptogram: AgAAAAAABk4DWZ4C28yUQAAAAAA=
                    eci: '05'
                    created_at: '2026-07-16T14:32:10Z'
                    expires_at: null
                cryptogram_only:
                  summary: 'Visa, cryptogram-only (include_network_token: false)'
                  value:
                    vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                    network_token:
                      network: VISA
                      status: ACTIVE
                      par: V0010013022280191
                      network_token_id: DNITHE302344816910968
                    cryptogram: AgAAAAAABk4DWZ4C28yUQAAAAAA=
                    eci: '05'
                    created_at: '2026-07-16T14:32:10Z'
                    expires_at: null
                mastercard_cryptogram_only:
                  summary: 'Mastercard, cryptogram-only (include_network_token: false)'
                  value:
                    vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
                    network_token:
                      network: MASTERCARD
                      status: ACTIVE
                      par: '50010013022280191'
                      network_token_id: MDNITHE302344816910968
                    cryptogram: AgAAAAAABk4DWZ4C28yUQAAAAAA=
                    eci: '02'
                    created_at: '2026-07-16T14:32:10Z'
                    expires_at: '2026-07-21T14:32:10Z'
        '400':
          description: >-
            Solicitud incorrecta: `INVALID_REQUEST`,
            `INSTRUMENT_NOT_TOKENIZABLE`, `PAYMENT_METHOD_NOT_ENROLLED`,
            `NETWORK_TOKEN_NOT_FOUND`, `TOKEN_NOT_ACTIVE`,
            `NETWORK_NOT_SUPPORTED` o `COUNTRY_NOT_SUPPORTED`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                network_token_not_found:
                  value:
                    code: NETWORK_TOKEN_NOT_FOUND
                    messages:
                      - Payment method has no network token.
        '403':
          description: >-
            Prohibido: `NETWORK_TOKEN_RETURN_NOT_ALLOWED` (la organización no
            tiene certificación PCI y la solicitud no estableció
            `include_network_token: false`), `PCI_MERCHANT_REQUIRED` (la
            organización no es un comercio con certificación PCI) o
            `PRODUCT_NOT_ENABLED` (el indicador del producto está desactivado
            para la organización).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                network_token_return_not_allowed:
                  value:
                    code: NETWORK_TOKEN_RETURN_NOT_ALLOWED
                    messages:
                      - >-
                        Returning the network token requires PCI certification.
                        Send include_network_token: false to receive the
                        cryptogram only, or contact your Key Account Manager
                        (KAM).
                pci_merchant_required:
                  value:
                    code: PCI_MERCHANT_REQUIRED
                    messages:
                      - >-
                        This endpoint is only available to PCI-certified
                        merchants.
        '404':
          description: >-
            No encontrado: `PAYMENT_METHOD_NOT_FOUND`. El `vaulted_token` no
            existe o no pertenece a tu organización (respuesta idéntica, sin
            filtrar si existe).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                payment_method_not_found:
                  value:
                    code: PAYMENT_METHOD_NOT_FOUND
                    messages:
                      - Payment method not found.
        '502':
          description: >-
            Error del proveedor: `PROVIDER_ERROR`. No se pudo contactar a la red
            de la tarjeta (Visa VTS / Mastercard MDES) o esta devolvió un error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                provider_error:
                  value:
                    code: PROVIDER_ERROR
                    messages:
                      - >-
                        The network token cryptogram service is temporarily
                        unavailable, please retry.
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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