Skip to main content
POST
This endpoint returns an on-demand network token cryptogram for a vaulted card and, by default, the card’s current network token (DPAN). A card’s network token alone cannot authorize a payment. Card schemes require a single-use cryptogram per transaction, and only Yuno can request it because Yuno holds the Token Requestor ID. Use this endpoint when you want to take a Yuno network token and authorize the transaction on your own PSP. You identify the card with its vaulted_token, the same identifier you use in Create Payment. Yuno resolves the card’s current network token internally and absorbs token rotation, so you always receive a consistent, current (DPAN, cryptogram, ECI) set.
The DPAN requires PCI certification: the cryptogram does notThe full network token (DPAN) is PAN-equivalent data, so the default response, which includes it, is only available to PCI-certified merchants. The cryptogram itself is not PAN-equivalent: it is single-use, short-lived, and bound to a specific DPAN, so it cannot authorize anything on its own.If your organization is not PCI-certified, send include_network_token: false to receive the cryptogram only. See Cryptogram-only mode below. To enable the product, contact your Key Account Manager (KAM).
Always submit a consistent pair. A cryptogram is bound to a specific network token. Submit the network_token.number (DPAN) returned in the same response together with its cryptogram and eci. Never pair a returned cryptogram with a previously stored DPAN. After a token rotation, a stored DPAN will no longer match. In cryptogram-only mode the same rule applies through the proxy: forward immediately after requesting the cryptogram, so the DPAN the proxy resolves is the one the cryptogram was generated for.

​
How it works

  1. Request a cryptogram right before you authorize. Every call generates a fresh, single-use cryptogram from the scheme: there is no idempotency, and duplicate calls return new cryptograms (no money moves).
  2. Submit network_token.number (DPAN), cryptogram, and eci to your PSP as a network-token transaction.
  3. If the authorization is declined and you retry, request a new cryptogram first. A used or stale cryptogram cannot be replayed.

​
Cryptogram-only mode

Send include_network_token: false and the response omits network_token.number (the DPAN) and network_token.token_data entirely. The network_token object keeps its non-PAN-equivalent metadata (network, status, par, network_token_id), and the response carries cryptogram and eci as usual. Because no PAN-equivalent data is returned, this mode does not require PCI certification. Pair it with the Forward Proxy to run a network-token transaction end-to-end without PAN-equivalent data ever entering your systems:
  1. Request the cryptogram with include_network_token: false.
  2. Build the forward request with the {{vaulted_token.<TOKEN>.network_token_number}} expression (and the network_token_expiration_* expressions) where the destination expects the DPAN. Include the cryptogram value directly in the body, since cryptograms are generated per transaction and the proxy does not resolve them as expressions.
  3. Send it through the proxy immediately: the proxy resolves the card’s current DPAN at forward time, and the cryptogram is bound to a specific DPAN. Requesting the cryptogram right before the forward keeps the pair consistent. A delay spanning a token rotation would make them mismatch.
The complete gate matrix: The last row is an explicit error by design: an integrator expecting network_token in the response gets a clear rejection, never a silently degraded response shape.

​
Requirements

To use this endpoint your organization must:
  • Have the product enabled for your organization.
  • Be onboarded for network tokens for the card’s brand and the requested country.
  • Be a PCI-certified merchant to receive the network token (DPAN) in the response. Cryptogram-only mode (include_network_token: false) does not require PCI certification.
The card referenced by vaulted_token must be an enrolled card of your organization that already has an active network token. Supported networks: Visa and Mastercard.
When you don’t need this endpoint. Recurring merchant-initiated transactions (MIT) authorize with the network token and the stored network_transaction_id and do not require a cryptogram. This endpoint is for customer-initiated transactions that need a fresh cryptogram.

​
Cryptogram lifetime

The cryptogram is single-use. Request it immediately before you authorize, and do not cache it.

​
Errors

Errors return a code and a messages array. The exact messages value per code: A vaulted_token that doesn’t exist and one that belongs to another organization both return the same PAYMENT_METHOD_NOT_FOUND, so there is no existence leak.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Body

application/json
​
vaulted_token
string<uuid>
required

The vaulted token of the card, the same identifier used as payment_method.vaulted_token in Create Payment. The card must be an enrolled card of your organization with an active network token.

Example:

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

​
country
string
required

ISO 3166-1 alpha-2 country code where the token will be used. Resolves the network token onboarding (organization + brand + country), with the same semantics as country in Create Payment.

Example:

"US"

​
amount
object

Optional. Forwarded to the scheme; recommended, as some scheme flows bind the amount.

​
include_network_token
boolean
default:true

Optional. Whether the response includes the PAN-equivalent parts of the network token: network_token.number (the DPAN) and network_token.token_data. Defaults to true, which requires your organization to be a PCI-certified merchant. Send false for a cryptogram-only response with no PAN-equivalent data (the network_token object keeps network, status, par and network_token_id) — available without PCI certification, designed to pair with the Forward Proxy, which resolves the DPAN at forward time via the network_token_number expression. A non-PCI organization that sends true or omits the field receives 403 NETWORK_TOKEN_RETURN_NOT_ALLOWED.

Example:

false

Response

Cryptogram generated.

​
vaulted_token
string

Echo of the request's vaulted token.

​
network_token
object

The card's current network token. Same shape returned by the PCI network-token retrieval. When the request sets include_network_token: false, the number (DPAN) and token_data fields are omitted entirely — the object keeps network, status, par and network_token_id.

​
cryptogram
string

A fresh, single-use cryptogram from the scheme, generated on every call. Submit it together with network_token.number (DPAN) and eci to your PSP.

Example:

"AgAAAAAABk4DWZ4C28yUQAAAAAA="

​
eci
string | null

Electronic Commerce Indicator. May be null for some Mastercard DSRP formats.

Example:

"05"

​
created_at
string<date-time>

Issuance timestamp (UTC).