Skip to content
API-Reference
/
/
Request cryptogram

Guardian API (EAP)

Download OpenAPI description
guardian-openapi.json
guardian-openapi.yaml
Overview
URL

https://hellgate.io/guardian

Starfish GmbH & Co. KG

hello@starfish.team

License

Hellgate API Terms

Languages
Servers
Managed instance of Guardian CPA

https://{cluster_id}.on-hellgate.cloud/

PCI Tokens

Management of card payment credentials under the ruling of PCI/DSS.

Operations

Network Tokens

Management of network tokens, including cryptograms for secure transactions.

Operations

Create token

Request

Create and provision a new network token with a card scheme.

There are three ways to create the token, which depend on the level of your PCI/DSS compliance:

Source ComplianceDescription
sessionMin. SAQ-A+This is the most common way to create a token. It will leverage the SDKs of Guardian to securely capture the cardholder data and send it encrypted to the API.
panMin. SAQ-D+In case you have the required compliance to handle cardholder data yourself, you can also just import the full data in exchange for a token.
pci_tokenMin. SAQ-A+Use an existing PCI token as source. The network token will be provisioned independently from the PCI token, such that the life-cycles of the tokens are not coupled.
Important information

Currently only Visa, Mastercard, American Express, and Discover are supported as card schemes. The network token will be provisioned with the card scheme.

Security
APIKey or AdminToken
Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
Bodyapplication/json
sourceobjectrequired
source.​typestringrequired
Discriminator
metadataobject

Metadata consisting of entries, each of which each includes a key and an associated value:

  • 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"}
curl -i -X POST \
  https://my-cluster-id.on-hellgate.cloud/api/network/tokens \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "source": {
      "type": "session"
    }
  }'

Responses

Success response

Bodyapplication/json
One of:
session_idstring(uuid)required
Response
application/json
{
  "session_id": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef"
}

Get tokens

Request

List all network tokens.

Security
APIKey or AdminToken
Query
limitinteger[ 1 .. 100 ]

The limit parameter defines the maximum number of rows returned in a single call and enables consecutive pagination using the next link provided in the response payload.

Default 20
curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens?limit=20' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
dataArray of objectsrequired
Example: [{"id":"123e4567-e89b-12d3-a456-426614174000","card":{"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"},"created_at":"2023-10-01T12:00:00Z","network_token":{"status":"active","type":"vts"}}]
data[].​idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174000"
data[].​cardobjectrequired
Example: {"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"}
data[].​card.​cardholder_namestring
Example: "John Doe"
data[].​card.​expiry_monthintegerrequired
Example: 12
data[].​card.​expiry_yearintegerrequired
Example: 2025
data[].​card.​masked_account_numberstringrequired
Example: "411111******1111"
data[].​card.​schemestringrequired
Enum"visa""mastercard""american express""discover""diners club""jcb""unionpay"
Example: "visa"
data[].​created_atstring(date-time)required
Example: "2023-10-01T12:00:00Z"
data[].​network_tokenobjectrequired
Example: {"status":"active","type":"vts"}
data[].​network_token.​scheme_referencestring

The ID of the network token at the scheme.

This value is only present if Delegated Authentication is active for the instance.

data[].​network_token.​statusstringrequired
Enum"active""inactive""deleted"
Example: "active"
data[].​network_token.​typestringrequired

The network token type.

Enum"vts""mdes""tms"
Example: "vts"
data[].​pci_token_idstring(uuid)

The ID of the PCI token that represents the card

Example: "32e4567-e89b-12d3-a456-426614174000"
data[].​metadataobject

Metadata consisting of entries, each of which each includes a key and an associated value:

  • 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"}
linksobjectrequired
Example: {"next":"https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"}
links.​nextstring(uri)required

The URL to the next page of results, if available.

Example: "https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"
Response
application/json
{
  "data": [
    { … }
  ],
  "links": {
    "next": "https://my-cluster-id.on-hellgate.cloud/network/tokens?after=123e4567-e89b-12d3-a456-426614174000&limit=20"
  }
}

Get token details

Request

Retrieves details of a specific network token by its ID.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to retrieve.

curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response.

Bodyapplication/json
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174000"
cardobjectrequired
Example: {"cardholder_name":"John Doe","expiry_month":12,"expiry_year":2025,"masked_account_number":"411111******1111","scheme":"visa"}
card.​cardholder_namestring
Example: "John Doe"
card.​expiry_monthintegerrequired
Example: 12
card.​expiry_yearintegerrequired
Example: 2025
card.​masked_account_numberstringrequired
Example: "411111******1111"
card.​schemestringrequired
Enum"visa""mastercard""american express""discover""diners club""jcb""unionpay"
Example: "visa"
created_atstring(date-time)required
Example: "2023-10-01T12:00:00Z"
network_tokenobjectrequired
Example: {"status":"active","type":"vts"}
network_token.​scheme_referencestring

The ID of the network token at the scheme.

This value is only present if Delegated Authentication is active for the instance.

network_token.​statusstringrequired
Enum"active""inactive""deleted"
Example: "active"
network_token.​typestringrequired

The network token type.

Enum"vts""mdes""tms"
Example: "vts"
pci_token_idstring(uuid)

The ID of the PCI token that represents the card

Example: "32e4567-e89b-12d3-a456-426614174000"
metadataobject

Metadata consisting of entries, each of which each includes a key and an associated value:

  • 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
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2023-10-01T12:00:00Z",
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "masked_account_number": "411111******1111",
    "scheme": "visa"
  },
  "network_token": {
    "status": "active",
    "type": "vts"
  },
  "pci_token_id": "32e4567-e89b-12d3-a456-426614174000"
}

Delete token

Request

Deletes a specific network token by its ID.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to delete.

curl -i -X DELETE \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response
No content

Request cryptogram

Request

Request a cryptogram (TAAV) for a given network token. The cryptogram is a dynamic value used to authenticate and authorize tokenized transactions, ensuring secure communication with the payment network.

Guardian supports two types of scenarios for cryptograms:

Type Description
ecomThis type is used in standard e-commerce transactions when a network token is in use.
dauthThis type is based on a delegated authentication setup with the card schemes and requires prior activation.
Security
APIKey or AdminToken
Path
idstring(uuid)required

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

Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
Bodyapplication/json
typestring
Discriminator
amountintegerrequired

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.

currency_codestringrequired

The three letter ISO-4217 currency code.

referencestringrequired
metadataobject

Metadata consisting of entries, each of which each includes a key and an associated value:

  • 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"}
curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens/{id}/cryptograms' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "type": "ecom",
    "amount": 1000,
    "currency_code": "EUR",
    "reference": "order_1234567890"
  }'

Responses

Success response with the requested cryptogram.

Bodyapplication/json
cryptogramstringrequired

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

Example: "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB"
ecistringrequired

The Electronic Commerce Indicator (ECI) from the issuer.

Example: "05"
expiry_monthintegerrequired
Example: 10
expiry_yearintegerrequired
Example: 2030
numberstringrequired
Example: "4122234533471157"
metadataobject

Metadata consisting of entries, each of which each includes a key and an associated value:

  • 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
application/json
{
  "cryptogram": "Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB",
  "eci": "05",
  "expiry_month": 10,
  "expiry_year": 2030,
  "number": "4122234533471157"
}

Get card art

Request

Get the card art associated with the network token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token for which to request the card art.

curl -i -X GET \
  'https://my-cluster-id.on-hellgate.cloud/api/network/tokens/{id}/card-art' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
base64_card_artstring(base64)

The base64 encoded image

heightinteger

Height of the image

widthinteger

Width of the image

mime_typestring

MimeType of the image

Response
application/json
{
  "base64_card_art": "string",
  "height": 0,
  "width": 0,
  "mime_type": "string"
}

Metadata Inquiries

Inquiries for card metadata based on PAN, PCI tokens, or network tokens.

Operations

Administration

Administrative operations for managing a Guardian instance, such as API keys.

Operations
Starfish GmbH & Co. KG © 2025