Saltar al contenido principal
POST
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. 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.
El DPAN requiere certificación PCI: el criptograma noEl 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 más abajo. Para habilitar el producto, comunícate con tu Key Account Manager (KAM).
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 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 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: 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 (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.
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: 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.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Cuerpo

application/json
vaulted_token
string<uuid>
requerido

El token en el vault de la tarjeta, el mismo identificador que se usa como payment_method.vaulted_token en Create Payment. La tarjeta debe ser una tarjeta inscrita de tu organización con un token de red activo.

Ejemplo:

"9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70"

country
string
requerido

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.

Ejemplo:

"US"

amount
object

Opcional. Se reenvía a la red; se recomienda, ya que algunos flujos de la red vinculan el monto.

include_network_token
boolean
predeterminado:true

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

Ejemplo:

false

Respuesta

Criptograma generado.

vaulted_token
string

Eco del token en el vault de la solicitud.

network_token
object

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.

cryptogram
string

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.

Ejemplo:

"AgAAAAAABk4DWZ4C28yUQAAAAAA="

eci
string | null

Electronic Commerce Indicator. Puede ser null en algunos formatos DSRP de Mastercard.

Ejemplo:

"05"

created_at
string<date-time>

Marca de tiempo de emisión (UTC).

expires_at
string<date-time> | null

Ú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é.

Ejemplo:

"2026-07-21T14:32:10Z"