> ## 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.
# Generate Network Token Cryptogram
> Generates a fresh, single-use network token cryptogram for a vaulted card so it can be authorized on an external PSP. PCI-certified merchants only.
This endpoint returns an on-demand **network token cryptogram** for a vaulted card, together with 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](/reference/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.
**PCI merchants only**
This endpoint is only available for PCI-certified merchants, because the response contains the full network token (DPAN). To enable it, contact your Key Account Manager (KAM).
**Always submit the returned 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.
## 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 simply 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.
## Requirements
To use this endpoint your organization must:
* Be a **PCI-certified merchant** (the response contains the DPAN).
* Have the **product enabled** for your organization.
* Be **onboarded for network tokens** for the card's brand and the requested `country`.
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`:
| 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` | The specific invalid field, e.g. "The field 'vaulted\_token' must be a valid uuid v4." |
| 403 | `PCI_MERCHANT_REQUIRED` | "This endpoint is only available to PCI-certified merchants." |
| 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." |
A `vaulted_token` that doesn't exist and one that belongs to another organization both return the same `PAYMENT_METHOD_NOT_FOUND` — no existence leak.
## OpenAPI
````yaml openapi/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
security:
- sec0: []
sec1: []
paths:
/network-tokens/cryptograms:
post:
summary: Generate Network Token Cryptogram
description: >-
Generates a fresh, single-use network token cryptogram for a vaulted
card, so it can be authorized on an external PSP. Available only to
PCI-certified merchants with the product enabled.
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: >-
The vaulted token of the card, the same identifier used as
`payment_method.vaulted_token` in [Create
Payment](https://docs.y.uno/reference/create-payment). The
card must be an enrolled card of your organization with an
active network token.
examples:
- 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
country:
type: string
description: >-
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.
examples:
- US
amount:
type: object
description: >-
Optional. Forwarded to the scheme; recommended, as some
scheme flows bind the amount.
properties:
currency:
type: string
description: ISO 4217 currency code.
examples:
- USD
value:
type: number
description: Amount value in the given currency.
examples:
- 49.99
examples:
default:
value:
vaulted_token: 9b2f4b1c-7f3a-4c2e-9b1a-2b3c4d5e6f70
country: US
amount:
currency: USD
value: 49.99
responses:
'201':
description: Cryptogram generated.
content:
application/json:
schema:
type: object
properties:
vaulted_token:
type: string
description: Echo of the request's vaulted token.
network_token:
type: object
description: >-
The card's current network token. Same shape returned by
the PCI network-token retrieval.
properties:
network:
type: string
description: Card network.
examples:
- VISA
number:
type: string
description: >-
The current DPAN (device/network PAN). **Always submit
this value with the returned `cryptogram`** — never a
previously stored DPAN.
examples:
- '4111111111111111'
status:
type:
- string
- 'null'
description: Network token status.
examples:
- ACTIVE
par:
type:
- string
- 'null'
description: Payment Account Reference.
network_token_id:
type:
- string
- 'null'
description: Network token identifier.
token_data:
type: object
properties:
iin:
type: string
lfd:
type: string
description: Last four digits of the DPAN.
expiration_month:
type: integer
examples:
- 7
expiration_year:
type: integer
examples:
- 2029
cryptogram:
type: string
description: >-
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.
examples:
- AgAAAAAABk4DWZ4C28yUQAAAAAA=
eci:
type:
- string
- 'null'
description: >-
Electronic Commerce Indicator. May be `null` for some
Mastercard DSRP formats.
examples:
- '05'
created_at:
type: string
format: date-time
description: Issuance timestamp (UTC).
examples:
default:
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'
'400':
description: >-
Bad request — `INVALID_REQUEST`, `INSTRUMENT_NOT_TOKENIZABLE`,
`PAYMENT_METHOD_NOT_ENROLLED`, `NETWORK_TOKEN_NOT_FOUND`,
`TOKEN_NOT_ACTIVE`, `NETWORK_NOT_SUPPORTED`, or
`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: >-
Forbidden — `PCI_MERCHANT_REQUIRED` (organization is not a
PCI-certified merchant) or `PRODUCT_NOT_ENABLED` (product flag is
off for the organization).
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
examples:
pci_merchant_required:
value:
code: PCI_MERCHANT_REQUIRED
messages:
- >-
This endpoint is only available to PCI-certified
merchants.
'404':
description: >-
Not found — `PAYMENT_METHOD_NOT_FOUND`. The `vaulted_token` does not
exist or does not belong to your organization (identical response,
no existence leak).
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: >-
Provider error — `PROVIDER_ERROR`. The card scheme (Visa VTS /
Mastercard MDES) could not be reached or returned an 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:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````