Request cryptogram
Request a cryptogram (TAVV) for a network token. Supports ecom (e-commerce) and dauth (delegated authentication).
Set mode to control how the cryptogram is returned. inline returns the full cryptogram payload (SAQ-D / RoC only). reference returns a short-lived, single-use cryptogram_reference that you forward with Forward cryptogram. When omitted, mode defaults to inline on SAQ-D / RoC and is forced to reference on SAQ-A / SAQ-A EP. See Network Tokens overview.
Send X-Idempotency-Key to make the request safe to retry. A repeat returns the original outcome with Idempotent-Replayed: true instead of requesting another cryptogram. In reference mode it returns the original reference and its expiry, also after the reference was forwarded or expired. In inline mode it returns the original cryptogram while Guardian holds it, for as long as a reference lives (15 minutes by default); after that, it returns the original response with number and cryptogram or dynamic_cvv set to null. A keyed inline replay whose held cryptogram can’t be read returns 503 CUSTODY_UNAVAILABLE and can be retried with the same key. When the configuration secret of the token service can’t be read, the request returns 503 SECRET_UNAVAILABLE, requests no cryptogram, and can be retried. A key reused with a different request returns 422 IDEMPOTENCY_KEY_MISMATCH, and a repeat while the original runs returns 409 IDEMPOTENCY_KEY_IN_USE. See Idempotency.
Authorizations
Headers
Makes the write safe to retry. A repeat with the same key, by the same credential, with the same request within 24 hours returns the original outcome with Idempotent-Replayed: true instead of executing again. 1 to 255 visible ASCII characters, sent once. Must not contain card data. See Idempotency.
1 - 255^[!-~]+$"cryptogram-7f3c2a9e-0001"
Body
- ECOM Request
- DAuth Request
The cryptogram to generate. type selects the variant.
Controls whether the cryptogram is returned in the response or kept inside Guardian.
inlinereturns the full cryptogram payload. Only allowed when the instance compliance level is SAQ-D or RoC.referencereturns a short-lived, single-usecryptogram_referenceinstead. Forward it with Forward cryptogram.
When omitted, the mode defaults to inline on SAQ-D / RoC and is forced to reference on SAQ-A / SAQ-A EP.
inline, reference Response
Success response with the requested cryptogram.
- TAVV
- Dynamic CVV
- Reference
Which variant you get is decided by the request's mode, not by a field you set.
mode: inlinereturns the cryptogram itself, tagged withtype—tavv, ordynamic_cvvfor American Express and Discover.mode: referencereturnscryptogram_referenceandexpires_atinstead, and carries notypefield. Tell it apart by the presence ofcryptogram_reference.
A replay of an inline request sent with X-Idempotency-Key returns the original response while Guardian holds the cryptogram (15 minutes by default). After that, it keeps the original keys, with number and cryptogram or dynamic_cvv set to null, and the original ECI, expiry, type and metadata. See Idempotency.