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.
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.
Cómo funciona
- 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).
- Envía
network_token.number(DPAN),cryptogramyecia tu PSP como una transacción con network token. - 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íainclude_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:
- Solicita el criptograma con
include_network_token: false. - Construye la solicitud de reenvío con la expresión
{{vaulted_token.<TOKEN>.network_token_number}}(y las expresionesnetwork_token_expiration_*) donde el destino espera el DPAN. Incluye el valor decryptogramdirectamente en el cuerpo, ya que los criptogramas se generan por transacción y el proxy no los resuelve como expresiones. - 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.
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
countrysolicitado. - 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.
vaulted_token debe ser una tarjeta inscrita de tu organización que ya tenga un network token activo.
Redes compatibles: Visa y Mastercard.
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_ates rechazado. null(hoy, Visa): la red no publica vigencia para este criptograma. Esto no significa que nunca venza. Úsalo de inmediato.
Errores
Los errores devuelven uncode y un arreglo messages. El valor exacto de messages por cada code:
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
Cuerpo
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.
"9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70"
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.
false
Respuesta
Criptograma generado.
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.
Ú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é.
"2026-07-21T14:32:10Z"