Skip to content
API-Reference
/
/
Delete security code

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

Refresh security code

Request

Request a refresh of the security code for the token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to check.

Headers
x-idempotency-keystring

Optional idempotency key to prevent duplicate processing

Example: order_12345_retry_001
curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/security-code' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001'

Responses

Success response

Bodyapplication/json
session_idstring(uuid)required
Response
application/json
{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Delete security code

Request

Remove the security code for the token.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to delete the security code for.

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

Responses

Success response (No Content)

Response
No content

Foward card data

Request

This endpoint allows to securely forward cardholder data to a certified third-party provider. It will inject sensitive cardholder data from the PCI token into the request before forwarding it.

Guardian forwards all headers from the request, except those it uses internally. To override these internal headers, you can provide a key-value pair that replaces the original header with your custom value.

The following example demonstrates this use case:

curl --location 'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/8744c9ea-a02b-4ae6-875c-b64fc333e3ef/forward' \
--header 'x-api-key: hlg-sbx-9876...'
--header 'x-own-header-name: x-api-key' \
--header 'x-own-header-value: 123456...' \
...

In the forwarded call, a header x-api-key: 123456... will be set, replacing the Guardian's x-api-key header.

Security
APIKey or AdminToken
Path
idstring(uuid)required

The ID of the token to forward.

Headers
x-destination-urlstring(uri)

The target URL to which the request shall be forwarded.

Important information

Guardian forwards calls only to whitelisted destination URLs. We include all major payment providers by default. In case you want to forward calls to a custom URL, please contact our support team to get the URL whitelisted.

Body
object

The payload the caller wants to forward to the third party provider.

To securely handle and inject sensitive cardholder data, predefined templates can be used. These templates help structure and standardize the data injection process while ensuring compliance with security and regulatory requirements.

PlaceholderDescription
{{ account_number }}The actual full account number of the stored card.
{{ cardholder_name }}The name of the cardholder.
{{ expiry_year }}Four digit year of the expiry date.
{{ expiry_month }}Two digit month of the expiry date.
{{ security_code }}The security code of the card in case it is present.

All injected data will be represented as a string in the payload. If a specific data type is required, such as a numeric representation of the expiry month, the data can be unwrapped and converted back to its original type as needed: {{ expiry_month | unwrap }}.

curl -i -X POST \
  'https://my-cluster-id.on-hellgate.cloud/api/pci/tokens/{id}/forward' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-destination-url: http://example.com' \
  -d '{
    "transactionReference": "My reference",
    "instruction": {
      "method": "card",
      "paymentInstrument": {
        "type": "plain",
        "cardNumber": "{{ account_number }}",
        "expiryDate": {
          "month": "{{ expiry_month | unwrap }}",
          "year": "{{ expiry_year | unwrap }}"
        }
      }
    },
    "value": {
      "currency": "EUR",
      "amount": 1000
    }
  }'

Responses

Success response

Body
object

The response from the third party provider.

Response
{}

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