Skip to content
/PCI Tokens

Guardian API (EAP)

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

https://hellgate.io/cpa/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

Create token

Request

Create a new token in the PCI/DSS scope. This type of token protects sensitive card payment credentials.

There are two 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.
Security
APIKey or AdminToken
Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
Bodyapplication/json
expires_ininteger[ 1 .. 2592000 ]

How many seconds after creation the token expires automatically.

sourceanyrequired
Default "session"
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/pci/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 tokens in the PCI/DSS scope.

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/pci/tokens?limit=20' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
dataArray of itemsrequired
Example: [{"id":"8744c9ea-a02b-4ae6-875c-b64fc333e3ef","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"}]
data[].​[0]object
Example: {"id":"8744c9ea-a02b-4ae6-875c-b64fc333e3ef","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"}
linksobjectrequired
Example: {"next":"https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"}
links.​nextstring(uri)required
Example: "https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"
Response
application/json
{
  "data": [
    { … }
  ],
  "links": {
    "next": "https://my-cluster-id.on-hellgate.cloud/pci/tokens?after=8744c9ea-a02b-4ae6-875c-b64fc333e3ef&limit=20"
  }
}

Get token details

Request

Get a token by its identifier.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to read.

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

Responses

Success response

Bodyapplication/json
idstring(uuid)required
Example: "8744c9ea-a02b-4ae6-875c-b64fc333e3ef"
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"
expires_atstring(date-time)
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": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef",
  "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 Tokens

Management of network tokens, including cryptograms for secure transactions.

Operations

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