Skip to content
API-Reference
/Metadata Inquiries/
Create inquiry

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

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

Create inquiry

Request

Create a new inquiry for card metadata based on either a PAN, an existing PCI token, or a network token.

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
source.​account_numberstringrequired

The card number (without separators)

Example: "4111111111111111"
source.​cardholder_namestring

The name of the cardholder

Example: "Bob Holder"
source.​expiry_yearinteger>= 2000required

The expiry year of the card

Example: 2025
source.​expiry_monthinteger[ 1 .. 12 ]required

The expiry month of the card

Example: 4
source.​security_codestring[ 3 .. 4 ] characters

The security code of the card

Information

The system will not permanently store the security code, but keep it in a ephemeral position for immediate use.

Example: "321"
curl -i -X POST \
  https://my-cluster-id.on-hellgate.cloud/api/metadata/inquiries \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: order_12345_retry_001' \
  -d '{
    "source": {
      "type": "pan",
      "account_number": "4111111111111111",
      "expiry_month": 12,
      "expiry_year": 2025,
      "security_code": "123"
    }
  }'

Responses

Success response

Bodyapplication/json
binstringrequired

The bank identification number.

Example: "411111"
schemeArray of stringsrequired

Scheme defines the brand of the card. A co-branded card will return multiple schemes.

Items Enum"visa""mastercard""american express""discover""diners club""jcb""unionpay""cartes bancaires""airplus"
Example: ["visa"]
typestring

The funding type of the card.

Enum"credit""debit""prepaid""charge""deferred""unknown"
Example: "credit"
segmentstring

The segment or category of the card.

Enum"consumer""commercial"
Example: "consumer"
currency_codestring= 3 characters

The three letter currency code of the card. See: ISO-4217

Example: "EUR"
issuer_namestring

The name of the issuing bank.

Example: "Starfish Bank"
issuer_country_codestring= 2 characters

A two letter country code of the issuer. ISO 3166-1 alpha-2

Example: "DE"
Response
application/json
{
  "bin": "411111",
  "scheme": [
    "visa"
  ],
  "type": "credit",
  "segment": "consumer",
  "currency_code": "EUR",
  "issuer_name": "Starfish Bank",
  "issuer_country_code": "DE"
}

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