Skip to main content
POST

Authorizations

Authorization
string
header
required

JWT bearer token obtained via the OAuth2 client-credentials grant from the platform Authentication API. The token's scopes gate the endpoints it may call, and its audience names the Guardian instance. This is the standard way to authenticate to Guardian.

Headers

X-Idempotency-Key
string

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.

Required string length: 1 - 255
Pattern: ^[!-~]+$
Example:

"cryptogram-7f3c2a9e-0001"

Path Parameters

id
string<uuid>
required

The ID of the token for which to request a cryptogram.

Body

application/json

The cryptogram to generate. type selects the variant.

type
string
required
Allowed value: "ecom"
amount
integer
required

The amount given in minor units (e.g. use 700 for 7€). Some currencies do not support minor units (e.g. Japanese Yen). In this case send in the full value, i.e. 100 for 100 JPY.

Example:

700

currency_code
string
required

The three letter ISO-4217 currency code.

Example:

"EUR"

reference
string
required
Example:

"order-1234567890"

mode
enum<string>

Controls whether the cryptogram is returned in the response or kept inside Guardian.

  • inline returns the full cryptogram payload. Only allowed when the instance compliance level is SAQ-D or RoC.
  • reference returns a short-lived, single-use cryptogram_reference instead. 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.

Available options:
inline,
reference
metadata
object

Metadata consisting of key-value entries.

  • Maximum 20 key-value pairs.
  • Maximum 20 characters per key.
  • Maximum 80 characters per value.
Example:

Response

Success response with the requested cryptogram.

Which variant you get is decided by the request's mode, not by a field you set.

  • mode: inline returns the cryptogram itself, tagged with type — tavv, or dynamic_cvv for American Express and Discover.
  • mode: reference returns cryptogram_reference and expires_at instead, and carries no type field. Tell it apart by the presence of cryptogram_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.

type
string
required
Allowed value: "tavv"
cryptogram
string | null
required
pci-sad

The token authentication verification value (TAVV) for the network token. null only in an idempotent replay after Guardian no longer holds the cryptogram.

eci
string
required

The Electronic Commerce Indicator (ECI) from the issuer.

expiry_month
integer
required
expiry_year
integer
required
number
string | null
required
pci-pan

The network token number. null only in an idempotent replay after Guardian no longer holds the cryptogram.

metadata
object

Metadata consisting of key-value entries.

  • Maximum 20 key-value pairs.
  • Maximum 20 characters per key.
  • Maximum 80 characters per value.
Example: