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

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

API Keys

Management of API keys for service access.

The capabilities an API keys has access to can be scoped to these areas:

  • API Keys
    • admin:api-keys:create
    • admin:api-keys:read
    • admin:api-keys:update
    • admin:api-keys:delete
  • Webhooks
    • admin:webhooks:create
    • admin:webhooks:read
    • admin:webhooks:delete
  • PCI Tokens
    • pci:tokens:create
    • pci:tokens:read
    • pci:tokens:update
    • pci:tokens:delete
    • pci:tokens:forward
  • Network Tokens
    • network:tokens:create
    • network:tokens:read
    • network:tokens:delete
    • network:tokens:use
  • Metadata Inquiries
    • metadata:inquiry:create
Operations

Webhooks

Management of webhooks for event notifications.

Guardian uses tiny events as notification payload. They give you the context of what happened and you can use this information to fetch more details via our API.

Please find the documentation about the callback on the endpoint that registers the webhook.

Operations
Starfish GmbH & Co. KG © 2025