Request a token session

Hellgate API (2.0)

Getting started

This reference is key for your comprehensive understanding of Hellgate® and, as such, essential for the successful use of our payment orchestration products.

Hellgate® APIs make use of RESTful conventions when possible and where it makes sense. All calls use the standard HTTP verbs to express access semantics, like GET, POST, PATCH, and DELETE. Other related conventions for our API can be found in the section below.

JSON Conventions

Resources are addressable by a UUIDv4 id property.
Property names are always in snake_case.
Hellgate® does not support empty strings. To unset a string value, use an explicit null value instead.
Temporal data is encoded in ISO 8601 strings.

Authentication

When you sign up for an account, you can authenticate with either OpenID Connect (OAuth 2.0), or Secret API keys. Unless explicitly stated, all endpoints require authentication using either your OIDC or Secret API Keys.

API Key

Hellgate® supports API keys to authenticate requests.

The keys are passed in via the HTTP header x-api-key.

curl --header 'X-API-Key: <SECRET>' \
  --request POST 'https://api.hellgate.io/...'

The keys must be handled with care and kept secure. Never hardcode the API keys in your source code, but keep them solely on your backend systems.

OpenID Connect

Hellgate® also supports OIDC id-tokens to authenticate requests. This option should be used when humans are interacting with the system. This is specifically the case when, for example, a front-end application is used to analyse data or modify the system state (for instance, our payment operations tool Ubersicht).

The authentication information is then passed in as a bearer token.

curl --header 'Authorization: Bearer <SECRET>' \
  --request POST 'https://api.hellgate.io/...'

Due to the fact that human users can be associated with many Hellgate® accounts, some requests require sending also a x-hellgate-account header to specify the context of the request.

API Use

API Versions

Hellgate® API will be updated regularly, to include new features and updates to existing ones. We package these changes into versions that can be addressed using a header field (x-hellgate-version).

If the there is no version specified in the header, the most recent version is being used.

curl --header 'x-hellgate-version: <SELECTED VERSION>' \
  --request POST 'https://api.hellgate.io/...'

Hellgate® sets the x-hellgate-version header on API responses, to tell the integrator which version is in use.

Idempotency

To prevent your system from handling requests twice and thus, for example, charging a customer twice, Hellgate® supports idempotency on requests to the API.

The behavior is controlled via the header field x-idempotency-Key.

curl --header 'x-idempotency-key: <key>' ...

Endpoints that return lists of objects support cursor-based pagination requests. By default, Hellgate® returns up to 50 objects per API call. If the number of objects in a response from a support endpoint exceeds the default, then an integration can use pagination to request a specific set of the results and/or to limit the number of returned objects.

If an endpoint supports pagination, the response body follows this structure:

{
  "current_page": 1,
  "page_size": 50,
  "total_items": 200,
  "total_pages": 4,
  "data": [...]
}

The single pages can be requested with query parameters:

Parameter	Type	Description
`limit`	`integer`	The maximum amount of objects to be returned on a page.
`page`	`integer`	The requested number of the page to return.

Processing Errors

Hellgate® uses the status codes to indicate the processing errors of the gateway operation as well as the results of connected services.

The response payload for processing errors follows a standard format:

{
  "status": "the HTTP status code",
  "classifier": "the classifer of the error",
  "message": "interesting for humans...",
  "validation_errors": []
}

The error object contains the classifier, which allows you to identify the error as well as a human-readable message. In case the error refers back to a badly formed request, validation_errors is included.

Validation errors itself hold a message describing the erroneous validation result and a path to point to the attribute in the JSON, which caused the problem.

Business Errors

The processing errors refer to the primary functions of Hellgate® and not necessarily to the related business logic. For example, a failed authorization due to insufficient funds will result in a 200 response, as the payment layer could successfully process the request (even though the business result is negative).

Download OpenAPI description

openapi.json

openapi.yaml

Overview

URL https://hellgate.io

Starfish GmbH & Co. KG hello@starfish.team

License Hellgate® API Terms

Servers

Hellgate® Sandbox

https://sandbox.hellgate.io/

Hellgate® Production

https://api.hellgate.io/

Customer Initiated Authentication

Operations

Merchant Initiated Authentication

Operations

Network Tokens

This API allows the utilization of network tokens to securely request cryptograms for authentication.

Operations

Authentication Management

Operations

Compliance Service

This API enables secure communication for exchanging Hellgate® tokens with original cardholder data.

Operations

Merchants

This API is used to manage merchants so that they can make use of network tokenization. The full lifecycle of a merchant is supported, from creation to deletion.

Operations

Tokens

This API allows you to manage cardholder data in compliance with the rules of PCI/DSS and to provision network tokens.

Operations

Import cardholder data

Request

Import PAN data in exchange for a Hellgate® token.

This endpoint allows a PCI DSS compliant entity to import PAN data in exchange for a Hellgate® token.

Headers

x-idempotency-keystring

An optional idempotency key for safely retrying requests.

Bodyapplication/json

cardholder_namestring

The name of the owner of the card

ℹ️ Information
Hellgate® only soft-deletes data. So in case of deletion this value will be anonymized.

Example: "John Doe"

expiry_monthintegerrequired

The number of month in a year (e.g. April is 4)

Example: 4

expiry_yearintegerrequired

The year given as four digit number (e.g. 2023)

Example: 2033

account_numberstringrequired

The full PAN of the card

Example: "4242424242424242"

security_codestring

The security code of the card

ℹ️ Information
Hellgate® will not permanently store the security code, but keep it in a ephemeral position for immediate use.

Example: "123"

curl -i -X POST \
  https://sandbox.hellgate.io/cde-import \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -H 'x-idempotency-key: string' \
  -d '{
    "cardholder_name": "John Doe",
    "expiry_month": 4,
    "expiry_year": 2033,
    "account_number": "4242424242424242",
    "security_code": "123"
  }'

Responses

Success response

Bodyapplication/json

idstring(uuid)required

The ID of the Hellgate® Token

Example: "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d"

cardholder_namestring

The name of the owner of the card

Example: "John Doe"

card_art_urlstring

The url linking to the card art endpoint

Example: "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b"

created_atstring(date-time)required

The date-time the payment-method was created (following ISO 8601)

Example: "2023-10-01T00:00:00Z"

expiry_monthintegerrequired

The number of month in a year (e.g. April is 4)

Example: 4

expiry_yearintegerrequired

The year given as four digit number (e.g. 2023)

Example: 2033

expires_atstring(date-time)

The date-time when the token will expire. Applicable only for ephemeral tokens.

Example: "2023-10-07T00:00:00Z"

invalidated_atstring(date-time)

The time the Hellgate Token was invalidated, because the underlying payment instrument was invalidated by the scheme.

issuer_identification_numberstringrequired

The issuer idenfication number (IIN) - also known as BIN

Example: "424242"

account_number_last_fourstring

Last four digits of the card number

account_number_lengthinteger

The total number of digits in the card number

masked_account_numberstringrequired

The full lenght of the card number, but masked to conform to PCI/DSS requirments

Example: "424242******4242"

bank_namestring

Issuer bank name

segmentstring

Card segment

Enum"business""consumer""commercial""other"

statusstring

The status of this Hellgate token.

Enum"active""invalid"

typestring

Card type

Enum"credit""debit"

country_codestring

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

network_token_statusstring

The status of the associated network token.

Status	Description
`active`	The network token is active and can be used.
`inactive`	The network token is inactive, which prevents using it. The reason can be for example suspended network token.
`pending`	A network token is currently being provisioned. As soon as this is available, the status is changed to `active`.
`failed`	A network token failed to be provisioned.
`deleted`	The network token is deleted and cannot be used again. It is also not possible to activate the network token again.
`not_available`	A network token can not be provisioned with the current configuration.

Enum"active""inactive""pending""deleted""failed""not_available"

network_token_status_reasonobject

schemestringrequired

The scheme in which the card was issued

Enum"VISA""Mastercard""American Express""Discover""Diners Club""JCB""UnionPay""Unknown"

identity_and_verificationstring

The type of ID&V submitted during the creation of the Hellgate token..

Enum"none""checked""skipped"

authentication_dataobject

supports_device_bindingboolean

business_keystring

This attribute holds the original business key under which the cardholder data was stored on the system from which it was imported to Hellgate®.

It can be used for reconciliation or reference purposes.

import_providerstring

The source from which the cardholder data was imported from.

The business_key attribute will refer to the original ID at this provider.

Response

application/json

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "cardholder_name": "John Doe",
  "card_art_url": "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "expires_at": "2023-10-07T00:00:00Z",
  "issuer_identification_number": "424242",
  "masked_account_number": "424242******4242",
  "network_token_status": "active",
  "scheme": "VISA"
}

Callbacks

Token Master Notification

post

Request a token session

Request

Create a session to start Hellgate® Tokenization using our SDK.

Bodyapplication/json

bypass_identificationboolean

Skips ID&V during tokenization if set to true

Default false

expiration_timeinteger[ 1 .. 2592000 ]

The expiry time is used to specify after how many seconds a Hellgate® token should be automatically deleted.

This type of tokens is useful for short-lived operations (guest checkout) that require a token to be used only once or for a limited time.

ℹ️ Information
If a token is created with an expiration time, no network-token will be provisioned.

curl -i -X POST \
  https://sandbox.hellgate.io/tokens/session \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{}'

Responses

Success response

Bodyapplication/json

session_idstring(uuid)required

The ID of the session which needs to be used to initialize the SDK.

Response

application/json

{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Request a CVC2 session

Request

Create a session to update the Security Code from a Hellgate® Token using our SDK.

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X POST \
  'https://sandbox.hellgate.io/tokens/{id}/refresh-session' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

session_idstring(uuid)required

The ID of the session which needs to be used to initialize the SDK.

Response

application/json

{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Get tokens

Request

Get a list of all Hellgate® tokens that belong to this account.

The results are grouped into pages. The caller can specify how many customers per page shall be listed (maximum is 500).

Query

limitinteger[ 1 .. 500 ]

The desired amount of records per page. The parameter defaults to 50 if it is omitted and has a maximum of 500.

pageinteger>= 1

The desired number of the page to return.

fromstring(date-time)

Return only network tokens created from this date (YYYY-MM-DD).

tostring(date-time)

Return only network tokens created up to this date (YYYY-MM-DD).

sortstring

It allows sorting the result by created_at. e.g sort=created_at+asc or sort=created_at+desc

network_token_statusstring

Requested status in list format e.g network_token_status=active or network_token_status=active,inactive

Enum"active""inactive""pending""deleted""failed""not_available"

schemestring

Requested card schemes in list format e.g scheme=VISA or scheme=VISA,MASTERCARD

Enum"VISA""Mastercard""American Express""Discover""Diners Club""JCB""UnionPay""Unknown"

business_keystring

Request tokens which the exact match of this value.

The business key is a reference of the original ID under which the cardholder data was stored on the system from which it was imported to Hellgate®.

curl -i -X GET \
  'https://sandbox.hellgate.io/tokens?business_key=string&from=2019-08-24T14%3A15%3A22Z&limit=1&network_token_status=active&page=1&scheme=VISA&sort=string&to=2019-08-24T14%3A15%3A22Z' \
  -H 'OIDC id-token: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

dataArray of objects

Example: [{"id":"5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d","cardholder_name":"John Doe","card_art_url":"https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b","created_at":"2023-10-01T00:00:00Z","expiry_month":4,"expiry_year":2033,"expires_at":"2023-10-07T00:00:00Z","issuer_identification_number":"424242","masked_account_number":"424242******4242","network_token_status":"active","scheme":"VISA"}]

paginationobject

The meta-data describing lists of data from the Hellgate® API. The pages are indexed from 1 up to the total_pages.

Example: {"current_page":1,"page_size":1,"total_items":1,"total_pages":1}

Response

application/json

{
  "data": [
    { … }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 1,
    "total_items": 1,
    "total_pages": 1
  }
}

Get token details

Request

Get a Hellgate® token by its identifer.

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X GET \
  'https://sandbox.hellgate.io/tokens/{id}' \
  -H 'OIDC id-token: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

idstring(uuid)required

The ID of the Hellgate® Token

Example: "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d"

cardholder_namestring

The name of the owner of the card

Example: "John Doe"

card_art_urlstring

The url linking to the card art endpoint

Example: "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b"

created_atstring(date-time)required

The date-time the payment-method was created (following ISO 8601)

Example: "2023-10-01T00:00:00Z"

expiry_monthintegerrequired

The number of month in a year (e.g. April is 4)

Example: 4

expiry_yearintegerrequired

The year given as four digit number (e.g. 2023)

Example: 2033

expires_atstring(date-time)

The date-time when the token will expire. Applicable only for ephemeral tokens.

Example: "2023-10-07T00:00:00Z"

invalidated_atstring(date-time)

The time the Hellgate Token was invalidated, because the underlying payment instrument was invalidated by the scheme.

issuer_identification_numberstringrequired

The issuer idenfication number (IIN) - also known as BIN

Example: "424242"

account_number_last_fourstring

Last four digits of the card number

account_number_lengthinteger

The total number of digits in the card number

masked_account_numberstringrequired

The full lenght of the card number, but masked to conform to PCI/DSS requirments

Example: "424242******4242"

bank_namestring

Issuer bank name

segmentstring

Card segment

Enum"business""consumer""commercial""other"

statusstring

The status of this Hellgate token.

Enum"active""invalid"

typestring

Card type

Enum"credit""debit"

country_codestring

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

network_token_statusstring

The status of the associated network token.

Status	Description
`active`	The network token is active and can be used.
`inactive`	The network token is inactive, which prevents using it. The reason can be for example suspended network token.
`pending`	A network token is currently being provisioned. As soon as this is available, the status is changed to `active`.
`failed`	A network token failed to be provisioned.
`deleted`	The network token is deleted and cannot be used again. It is also not possible to activate the network token again.
`not_available`	A network token can not be provisioned with the current configuration.

Enum"active""inactive""pending""deleted""failed""not_available"

network_token_status_reasonobject

schemestringrequired

The scheme in which the card was issued

Enum"VISA""Mastercard""American Express""Discover""Diners Club""JCB""UnionPay""Unknown"

identity_and_verificationstring

The type of ID&V submitted during the creation of the Hellgate token..

Enum"none""checked""skipped"

authentication_dataobject

supports_device_bindingboolean

business_keystring

This attribute holds the original business key under which the cardholder data was stored on the system from which it was imported to Hellgate®.

It can be used for reconciliation or reference purposes.

import_providerstring

The source from which the cardholder data was imported from.

The business_key attribute will refer to the original ID at this provider.

Response

application/json

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "cardholder_name": "John Doe",
  "card_art_url": "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "expires_at": "2023-10-07T00:00:00Z",
  "issuer_identification_number": "424242",
  "masked_account_number": "424242******4242",
  "network_token_status": "active",
  "scheme": "VISA"
}

Delete a token

Request

Remove a Hellgate® token

🚧 Warnings
This operation cannot be undone
This operation will also delete enrollments of the token on devices

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X DELETE \
  'https://sandbox.hellgate.io/tokens/{id}' \
  -H 'OIDC id-token: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response

No content

Callbacks

Token Master Notification

post

Check CVC2 availability

Request

Get an indicator if security information for a stored Hellgate® token is still available.

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X GET \
  'https://sandbox.hellgate.io/tokens/{id}/security-code' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

security_code_availableboolean

Security Data available in the system

Response

application/json

{
  "security_code_available": true
}

Invalidate CVC2

Request

Invalidate the cache for Hellgate® CVC2.

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X POST \
  'https://sandbox.hellgate.io/tokens/{id}/consume' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Success response (No Content)

Response

No content

Network Token provision

Request

If the provisioning of a network token status is failed or not available for any reason, this endpoint can be used to provision a network token.

Path

idstring(uuid)required

The ID of the Hellgate® token

curl -i -X POST \
  'https://sandbox.hellgate.io/tokens/{id}/provisions' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json

idstring(uuid)required

The ID of the Hellgate® Token

Example: "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d"

cardholder_namestring

The name of the owner of the card

Example: "John Doe"

card_art_urlstring

The url linking to the card art endpoint

Example: "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b"

created_atstring(date-time)required

The date-time the payment-method was created (following ISO 8601)

Example: "2023-10-01T00:00:00Z"

expiry_monthintegerrequired

The number of month in a year (e.g. April is 4)

Example: 4

expiry_yearintegerrequired

The year given as four digit number (e.g. 2023)

Example: 2033

expires_atstring(date-time)

The date-time when the token will expire. Applicable only for ephemeral tokens.

Example: "2023-10-07T00:00:00Z"

invalidated_atstring(date-time)

The time the Hellgate Token was invalidated, because the underlying payment instrument was invalidated by the scheme.

issuer_identification_numberstringrequired

The issuer idenfication number (IIN) - also known as BIN

Example: "424242"

account_number_last_fourstring

Last four digits of the card number

account_number_lengthinteger

The total number of digits in the card number

masked_account_numberstringrequired

The full lenght of the card number, but masked to conform to PCI/DSS requirments

Example: "424242******4242"

bank_namestring

Issuer bank name

segmentstring

Card segment

Enum"business""consumer""commercial""other"

statusstring

The status of this Hellgate token.

Enum"active""invalid"

typestring

Card type

Enum"credit""debit"

country_codestring

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

network_token_statusstring

The status of the associated network token.

Status	Description
`active`	The network token is active and can be used.
`inactive`	The network token is inactive, which prevents using it. The reason can be for example suspended network token.
`pending`	A network token is currently being provisioned. As soon as this is available, the status is changed to `active`.
`failed`	A network token failed to be provisioned.
`deleted`	The network token is deleted and cannot be used again. It is also not possible to activate the network token again.
`not_available`	A network token can not be provisioned with the current configuration.

Enum"active""inactive""pending""deleted""failed""not_available"

network_token_status_reasonobject

schemestringrequired

The scheme in which the card was issued

Enum"VISA""Mastercard""American Express""Discover""Diners Club""JCB""UnionPay""Unknown"

identity_and_verificationstring

The type of ID&V submitted during the creation of the Hellgate token..

Enum"none""checked""skipped"

authentication_dataobject

supports_device_bindingboolean

business_keystring

This attribute holds the original business key under which the cardholder data was stored on the system from which it was imported to Hellgate®.

It can be used for reconciliation or reference purposes.

import_providerstring

The source from which the cardholder data was imported from.

The business_key attribute will refer to the original ID at this provider.

Response

application/json

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "cardholder_name": "John Doe",
  "card_art_url": "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "expires_at": "2023-10-07T00:00:00Z",
  "issuer_identification_number": "424242",
  "masked_account_number": "424242******4242",
  "network_token_status": "active",
  "scheme": "VISA"
}

Stripe Backup

Operations

Reconciliation

Operations

Hellgate API (2.0)

Getting started

JSON Conventions

Authentication

API Key

OpenID Connect

API Use

API Versions

Idempotency

Pagination

Processing Errors

Business Errors

Customer Initiated Authentication

Merchant Initiated Authentication

Network Tokens

Authentication Management

Compliance Service

Merchants

Tokens

Import cardholder data

Request

Responses

Callbacks

Request a token session

Request

Responses

Request a CVC2 session

Request

Responses

Get tokens

Request

Responses

Get token details

Request

Responses

Delete a token

Request

Responses

Callbacks

Check CVC2 availability

Request

Responses

Invalidate CVC2

Request

Responses

Network Token provision

Request

Responses

Stripe Backup

Reconciliation