Hellgate API (2.0)

Download OpenAPI specification:Download

Starfish GmbH & Co. KG: hello@starfish.team URL: https://hellgate.io License: Hellgate® API Terms

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>' ...

Pagination

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).

Compliance Service

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

Forward cardholder data

This endpoint allows to securely forward cardholder data to a certified third-party provider. It will inject sensitive cardholder data, referenced by a Hellgate® token, into the request before forwarding it.

Hellgate requires certain HTTP headers for this feature. These headers are reserved and cannot be used by the caller:

  • x-api-key - required for request authentication
  • x-hellgate-token - required to identify the Hellgate token to use for the request
  • x-destination-url - required to define the target URL to which the request shall be forwarded
  • x-hellgate-version - optional to define the API version to use for the request

In order to use the same header keys for the third-party provider, Hellgate allows to define key-value pairs with are resolved and injected as HTTP headers before forwarding to the third-party provider. The following example illustrates the use:

curl --location 'https://sandbox.hellgate.io/forward' \
--header 'x-api-key: hlg-sbx-9876...'
--header 'x-own-header-key: x-api-key' \
--header 'x-own-header-value: 123456...' \
...

The caller defines a custom header x-own-header-key with the value x-api-key which was previously reserved by Hellgate. The key-value pairs are matched on the term own-header in the example above.

SecurityAPIKeyAuth
Request
header Parameters
x-hellgate-token
required
string <uuid>

The ID of the Hellgate token to use for the request.

x-destination-url
required
string <uri>

The target URL to which the request shall be forwarded.

Only allowed target URLs by the merchant can be request.

Request Body schema: application/json
object

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

In order to inject sensitive cardholder data templates can be used.

Placeholder Description
{{ account_number }} The actual full account number of the stored card.
{{ expiration_year }} Four digit year of the expiration date.
{{ expiration_month }} Two digit month of the expiration date.
{{ security_code }} The security code of the card in case it is present.
Responses
200

Success response

400

Error response (Enrollment Logic)

401

Unauthorized

403

Forbidden

407

No valid means of authentication was provided for the proxy

502

A non-processable response was received from the upstream server

503

The server is currently not able to handle the request

504

The server did not receive any response in time from the upstream server

post/forward
Request samples
application/json
{ }
Response samples
application/json
{ }

Network Tokens

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

Request a cryptogram

Request a cryptogram (i.e. TAVV) for a Hellgate® token

SecurityAPIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the Hellgate® token

header Parameters
x-idempotency-key
string

An optional idempotency key for safely retrying requests.

Request Body schema: application/json
amount
required
integer (Amount) >= 0

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_code
required
string (CurrencyCode)

The three letter currency code. See: ISO-4217

merchant_id
required
string <uuid>

The ID of the merchant for whom the authentication is requested

reference
required
string

A reference to the payment

Responses
200

Success response

401

Unauthorized

403

Forbidden

404

Not found

422

Validation error

post/tokens/{id}/payment-data
Request samples
application/json
{
  • "amount": 10000,
  • "currency_code": "EUR",
  • "merchant_id": "00000000-0000-0000-0000-000000000000",
  • "reference": "1234567890"
}
Response samples
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "amount": 10000,
  • "currency_code": "EUR",
  • "encrypted_authentication_data": "eyJhbGc...",
  • "merchant_id": "00000000-0000-0000-0000-000000000000",
  • "reference": "1234567890",
  • "success": true,
  • "token_id": "00000000-0000-0000-0000-000000000000"
}

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.

Create a merchant

Create a new merchant.

Merchants represent legal entities which are interacting with the card networks. Onboarding merchants for an account is a prerequisite for creating network tokens. Depending on the setup of the account, this allows to render complex ecommerce ecosystem setups.

SecurityBearer or APIKeyAuth
Request
header Parameters
x-idempotency-key
string

An optional idempotency key for safely retrying requests.

Request Body schema: application/json
company_city
required
string

The city in the merchant's primary address.

country_code
required
string (ISO3166-2-CountryCode)

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

legal_name
required
string

The name of the merchant

website_url
required
string <uri>

The URL of the merchant's website

Responses
200

Success response

401

Unauthorized

403

Forbidden

422

Validation error

post/merchants
Request samples
application/json
{
  • "company_city": "Berlin",
  • "country_code": "DE",
  • "legal_name": "Example Merchant",
  • "website_url": "https://example.com"
}
Response samples
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "created_at": "2023-10-10T00:00:00Z",
  • "company_city": "Berlin",
  • "country_code": "DE",
  • "encryption_key": "eyJhbGciOiJSUzI1NiIsImVudGl0bGVtZW50IjoiYWF4NXdq...",
  • "legal_name": "Example Merchant",
  • "website_url": "https://example.com"
}

Get merchants

Get a list of all merchants 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).

SecurityBearer or APIKeyAuth
Request
query Parameters
limit
integer [ 1 .. 500 ]

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

page
integer >= 1

The desired number of the page to return.

sort
string

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

from
string <date-time>

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

to
string <date-time>

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

country_code
string (CountryCode_3166_2)

Contry code in a list format e.g country_code=DE, country_code=US,AUS.

Responses
200

Success response

401

Unauthorized

403

Forbidden

get/merchants
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get merchant details

Get the information of a merchant.

SecurityBearer or APIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the merchant

Responses
200

Success response

401

Unauthorized

403

Forbidden

404

Not found

get/merchants/{id}
Request samples
Response samples
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "created_at": "2023-10-10T00:00:00Z",
  • "company_city": "Berlin",
  • "country_code": "DE",
  • "encryption_key": "eyJhbGciO[redacted]",
  • "legal_name": "Example Merchant",
  • "website_url": "https://example.com"
}

Update merchant details

Update the information of a merchant.

SecurityBearer or APIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the merchant

Request Body schema: application/json
company_city
string

The city in the merchant's primary address.

country_code
string (ISO3166-2-CountryCode)

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

legal_name
string

The name of the merchant

website_url
string <uri>

The URL of the merchant's website

Responses
200

Success response

401

Unauthorized

403

Forbidden

404

Not found

patch/merchants/{id}
Request samples
application/json
{
  • "company_city": "string",
  • "country_code": "string",
  • "legal_name": "string",
  • "website_url": "http://example.com"
}
Response samples
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "created_at": "2023-10-10T00:00:00Z",
  • "company_city": "Berlin",
  • "country_code": "DE",
  • "encryption_key": "eyJhbGciO[redacted]",
  • "legal_name": "Example Merchant",
  • "website_url": "https://example.com"
}

Delete a merchant

Remove a merchant from Hellgate.

🚧 Warning

This action is irreversible.

SecurityBearer or APIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the merchant

Responses
204

Success response (No Content)

401

Unauthorized

403

Forbidden

delete/merchants/{id}
Request samples
Response samples
application/json
{
  • "code": 401,
  • "message": "No valid means of authentication was provided",
  • "classifier": "UNAUTHORIZED"
}

Tokens

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

Import cardholder data

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.

SecurityAPIKeyAuth
Request
header Parameters
x-idempotency-key
string

An optional idempotency key for safely retrying requests.

Request Body schema: application/json
cardholder_name
string

The name of the owner of the card

ℹ️ Information

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

expiry_month
required
integer

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

expiry_year
required
integer

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

account_number
required
string

The full PAN of the card

security_code
string

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.

Responses
200

Success response

401

Unauthorized

422

Validation error

Callbacks
postToken Master Notification
post/cde-import
Request samples
application/json
{
  • "cardholder_name": "John Doe",
  • "expiry_month": 4,
  • "expiry_year": 2033,
  • "account_number": "4242424242424242",
  • "security_code": "123"
}
Response samples
application/json
{
  • "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  • "cardholder_name": "John Doe",
  • "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"
}
Callback payload samples
POST: Token Master Notification
application/json
{
  • "id": "b21ecb35-6c95-46d9-afb2-c130cdf1750f",
  • "created_at": "2023-01-01T00:00:00Z",
  • "event_type": "token.created",
  • "token": {}
}

Request a token session

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

SecurityAPIKeyAuth
Request
Request Body schema: application/json
bypass_identification
boolean
Default: false

Skips ID&V during tokenization if set to true

expiration_time
integer [ 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.

Responses
200

Success response

401

Unauthorized

403

Forbidden

post/tokens/session
Request samples
application/json
{
  • "bypass_identification": false,
  • "expiration_time": 1
}
Response samples
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Get tokens

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).

SecurityBearer or APIKeyAuth
Request
query Parameters
limit
integer [ 1 .. 500 ]

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

page
integer >= 1

The desired number of the page to return.

from
string <date-time>

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

to
string <date-time>

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

sort
string

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

network_token_status
string (NetworkTokenStatus)

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"
scheme
string (CardScheme)

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"
Responses
200

Success response

401

Unauthorized

403

Forbidden

get/tokens
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get token details

Get a Hellgate® token by its identifer.

SecurityBearer or APIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the Hellgate® token

Responses
200

Success response

401

Unauthorized

403

Forbidden

404

Not found

get/tokens/{id}
Request samples
Response samples
application/json
{
  • "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  • "cardholder_name": "John Doe",
  • "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

Remove a Hellgate® token

🚧 Warnings

  • This operation cannot be undone
  • This operation will also delete enrollments of the token on devices
SecurityBearer or APIKeyAuth
Request
path Parameters
id
required
string <uuid>

The ID of the Hellgate® token

Responses
204

Success response (No Content)

401

Unauthorized

403

Forbidden

404

Not found

Callbacks
postToken Master Notification
delete/tokens/{id}
Request samples
Response samples
application/json
{
  • "code": 401,
  • "message": "No valid means of authentication was provided",
  • "classifier": "UNAUTHORIZED"
}
Callback payload samples
POST: Token Master Notification
application/json
{
  • "id": "b21ecb35-6c95-46d9-afb2-c130cdf1750f",
  • "created_at": "2023-01-01T00:00:00Z",
  • "event_type": "token.created",
  • "token": {}
}