Network Tokens

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.

POST

api

network

tokens

{id}

cryptograms

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/cryptograms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "ecom",
  "amount": 1000,
  "currency_code": "EUR",
  "reference": "order_1234567890"
}
'

{
  "type": "tavv",
  "cryptogram": "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB",
  "eci": "05",
  "expiry_month": 10,
  "expiry_year": 2030,
  "number": "4122234533471157"
}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

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.

Path Parameters

string<uuid>

required

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

Body

application/json

ECOM Request
DAuth Request

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:

{
  "my_key_one": "my_value_one",
  "my_key_two": "my_value_two"
}

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: 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.

type

string

required

Allowed value: "tavv"

cryptogram

string

required

pci-sad

The token authentication verification value (TAVV) for the network token.

eci

string

required

The Electronic Commerce Indicator (ECI) from the issuer.

expiry_month

integer

required

expiry_year

integer

required

number

string

required

pci-pan

metadata

object

Metadata consisting of key-value entries.

Maximum 20 key-value pairs.
Maximum 20 characters per key.
Maximum 80 characters per value.

Example:

{ "order_ref": "order-1234567890" }

⌘I

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/cryptograms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "ecom",
  "amount": 1000,
  "currency_code": "EUR",
  "reference": "order_1234567890"
}
'

{
  "type": "tavv",
  "cryptogram": "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB",
  "eci": "05",
  "expiry_month": 10,
  "expiry_year": 2030,
  "number": "4122234533471157"
}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

Getting Started

Tokens

Metadata

Admin

Request cryptogram

Authorizations

Path Parameters

Body

Response