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.
id
property.snake_case
.null
value instead.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.
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.
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.
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.
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. |
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.
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).
This API enables secure communication for exchanging Hellgate® tokens with original 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 authenticationx-hellgate-token
- required to identify the Hellgate token to use for the requestx-destination-url
- required to define the target URL to which the request shall be forwardedx-hellgate-version
- optional to define the API version to use for the requestIn 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-name: x-api-key' \
--header 'x-own-header-value: 123456...' \
...
The caller defines a custom header x-own-header-name
with the value x-api-key
which was previously reserved by Hellgate.
The key-value pairs are matched on the term x-own-header
in the example above.
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. |
Success response
Error response (Enrollment Logic)
Unauthorized
Forbidden
No valid means of authentication was provided for the proxy
A non-processable response was received from the upstream server
The server is currently not able to handle the request
The server did not receive any response in time from the upstream server
{ }
{ }
This API allows the utilization of network tokens to securely request cryptograms for authentication.
Request a cryptogram (i.e. TAVV) for a Hellgate® token
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 |
Success response
Unauthorized
Forbidden
Not found
Validation error
{- "amount": 10000,
- "currency_code": "EUR",
- "merchant_id": "00000000-0000-0000-0000-000000000000",
- "reference": "1234567890"
}
{- "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"
}
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 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.
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 |
identity_and_verification_enabled | boolean The flag indicates if the 3DS identity and verification is required or not (only allowed for primary) |
3ds_enabled required | boolean Indicates if 3DS is available or not for the Merchant |
default_currency | string (CurrencyCode) The three letter currency code. See: ISO-4217 |
default_merchant_id | string The id for the Merchant |
Array of objects (MerchantScheme) The schemes supported by the merchant (required if merchant has a merchant_id) |
Success response
Unauthorized
Forbidden
Validation error
{- "company_city": "Berlin",
- "country_code": "DE",
- "legal_name": "Example Merchant",
- "identity_and_verification_enabled": false,
- "3ds_enabled": true,
- "default_currency": "EUR",
- "default_merchant_id": 1234567890,
- "schemes": {
- "name": "visa",
- "acquirer_bin": 40001,
- "requestor_id": "123456789.visa",
- "requestor_name": "3dsclient.local.visa",
- "category_code": 3200,
- "merchant_id": "",
- "merchant_name": ""
}
}
{- "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",
}
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).
Success response
Unauthorized
Forbidden
{- "data": [
- {
- "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",
- "type": "submerchant",
- "identity_and_verification_enabled": false,
- "3ds_enabled": true,
- "default_currency": "EUR",
- "default_merchant_id": 1234567890,
- "schemes": {
- "name": "visa",
- "acquirer_bin": 40001,
- "requestor_id": "123456789.visa",
- "requestor_name": "3dsclient.local.visa",
- "category_code": 3200,
- "merchant_id": "",
- "merchant_name": ""
}
}
], - "pagination": {
- "current_page": 1,
- "page_size": 1,
- "total_items": 1,
- "total_pages": 1
}
}
Get the information of a merchant.
Success response
Unauthorized
Forbidden
Not found
{- "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",
- "type": "submerchant",
- "identity_and_verification_enabled": false,
- "3ds_enabled": true,
- "default_currency": "EUR",
- "default_merchant_id": 1234567890,
- "schemes": {
- "name": "visa",
- "acquirer_bin": 40001,
- "requestor_id": "123456789.visa",
- "requestor_name": "3dsclient.local.visa",
- "category_code": 3200,
- "merchant_id": "",
- "merchant_name": ""
}
}
Update the information of a merchant.
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 |
identity_and_verification_enabled | boolean The flag indicates if the 3DS identity and verification is required or not (only allowed for primary) |
3ds_enabled required | boolean Indicates if 3DS is available or not for the Merchant |
default_currency | string (CurrencyCode) The three letter currency code. See: ISO-4217 |
default_merchant_id | string The id for the Merchant |
Array of objects (MerchantScheme) The schemes supported by the merchant (required if merchant has a merchant_id) |
Success response
Unauthorized
Forbidden
Not found
{- "company_city": "string",
- "country_code": "string",
- "legal_name": "string",
- "identity_and_verification_enabled": true,
- "3ds_enabled": true,
- "default_currency": "string",
- "default_merchant_id": "string",
- "schemes": [
- {
- "name": "visa",
- "acquirer_bin": "string",
- "requestor_id": "string",
- "requestor_name": "string",
- "category_code": 0,
- "merchant_id": "string",
- "merchant_name": "string"
}
]
}
{- "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",
- "type": "submerchant",
- "identity_and_verification_enabled": false,
- "3ds_enabled": true,
- "default_currency": "EUR",
- "default_merchant_id": 1234567890,
- "schemes": {
- "name": "visa",
- "acquirer_bin": 40001,
- "requestor_id": "123456789.visa",
- "requestor_name": "3dsclient.local.visa",
- "category_code": 3200,
- "merchant_id": "",
- "merchant_name": ""
}
}
Remove a merchant from Hellgate.
🚧 Warning
This action is irreversible.
Success response (No Content)
Unauthorized
Forbidden
{- "code": 401,
- "message": "No valid means of authentication was provided",
- "classifier": "UNAUTHORIZED"
}
This API allows you to manage cardholder data in compliance with the rules of PCI/DSS and to provision network tokens.
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.
Success response
Unauthorized
Validation error
{- "cardholder_name": "John Doe",
- "expiry_month": 4,
- "expiry_year": 2033,
- "account_number": "4242424242424242",
- "security_code": "123"
}
{- "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"
}
{- "id": "b21ecb35-6c95-46d9-afb2-c130cdf1750f",
- "created_at": "2023-01-01T00:00:00Z",
- "event_type": "token.created",
- "token": {
- "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
- "cardholder_name": "John Doe",
- "created_at": "2023-10-01T00:00:00Z",
- "expiry_month": 4,
- "expiry_year": 2033,
- "issuer_identification_number": "424242",
- "masked_account_number": "424242******4242",
- "network_token_status": "active",
- "scheme": "VISA"
}
}
Create a session to start Hellgate® Tokenization using our SDK.
Success response
Unauthorized
Forbidden
{- "bypass_identification": false,
- "expiration_time": 1
}
{- "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}
Get an indicator if security information for a stored Hellgate® token is still available.
Success response
Unauthorized
Forbidden
Not found
{- "security_code_available": true
}
Create a session to update the Security Code from a Hellgate® Token using our SDK.
Success response
Unauthorized
Forbidden
Not found
{- "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}
Removes a Security Code from the Cache.
Success response (No Content)
Unauthorized
Forbidden
Not found
{- "code": 401,
- "message": "No valid means of authentication was provided",
- "classifier": "UNAUTHORIZED"
}
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).
Success response
Unauthorized
Forbidden
{- "data": [
- {
- "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"
}
], - "pagination": {
- "current_page": 1,
- "page_size": 1,
- "total_items": 1,
- "total_pages": 1
}
}
Get a Hellgate® token by its identifer.
Success response
Unauthorized
Forbidden
Not found
{- "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"
}
Remove a Hellgate® token
🚧 Warnings
- This operation cannot be undone
- This operation will also delete enrollments of the token on devices
Success response (No Content)
Unauthorized
Forbidden
Not found
{- "code": 401,
- "message": "No valid means of authentication was provided",
- "classifier": "UNAUTHORIZED"
}
{- "id": "b21ecb35-6c95-46d9-afb2-c130cdf1750f",
- "created_at": "2023-01-01T00:00:00Z",
- "event_type": "token.created",
- "token": {
- "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
- "cardholder_name": "John Doe",
- "created_at": "2023-10-01T00:00:00Z",
- "expiry_month": 4,
- "expiry_year": 2033,
- "issuer_identification_number": "424242",
- "masked_account_number": "424242******4242",
- "network_token_status": "active",
- "scheme": "VISA"
}
}
Requests the import of cardholder data from a third-party vault (currently supported source is stripe.com).
The import processed in the background and its status can be queried by the returned import ID. During preparation and processing of a job it is not possible to create another import.
Success response
Unauthorized
Forbidden
Validation error
{- "provider": "stripe",
- "stripe": {
- "api_key": "sk_test_****"
}
}
{- "id": "63820065-af1a-42fa-b96f-8d928fc6c2ec",
- "created_at": "2023-10-10T00:00:00Z",
- "provider": "stripe",
- "status": "preparing",
- "stripe": {
- "api_key": "[REDACTED]"
}, - "attemts": 0,
- "successes": 0,
- "failures": 0
}
Show details of a token import
Success response
Unauthorized
Forbidden
Validation error
{- "id": "63820065-af1a-42fa-b96f-8d928fc6c2ec",
- "created_at": "2023-10-10T00:00:00Z",
- "provider": "stripe",
- "status": "preparing",
- "stripe": {
- "api_key": "[REDACTED]"
}, - "attemts": 0,
- "successes": 0,
- "failures": 0
}
Abort a running token import.
This is possible while the import is not finished or already aborted.
Success response
Unauthorized
Forbidden
Validation error
{- "value": {
- "id": "63820065-af1a-42fa-b96f-8d928fc6c2ec",
- "created_at": "2023-10-10T00:00:00Z",
- "finished_at": "2023-10-10T01:00:00Z",
- "provider": "stripe",
- "status": "aborted",
- "stripe": {
- "api_key": "[REDACTED]"
}, - "attemts": 47,
- "successes": 1,
- "failures": 46
}
}
Success response
Unauthorized
Forbidden
{- "data": [
- {
- "reason": "destination_error",
- "context": { }
}
], - "pagination": {
- "current_page": 1,
- "page_size": 1,
- "total_items": 1,
- "total_pages": 1
}
}
This report gives allowes to reconcile imported tokens from third-party sources.
The report contains all Hellgate® tokens of the current account. The tokens are annotated with a import_provider
and the corresponding business_key
(i.e. the ID of the cardholder data at the provider).
Success response
Unauthorized
Forbidden
id,import_provider,business_key,created_at "d3e14053-52c0-4b4a-9b24-6931a1eb2eb5",,,"2024-08-13 15:44:26.559568" "cbc2c85f-53ce-4cd2-b7cf-d74c7c3983c2",,,"2024-08-13 14:59:25.67196" "1d15fcbf-78f0-4a7f-b114-c918f6f7b144",,,"2024-08-13 15:00:38.871148" "364073f3-47fd-4210-bb8a-5bc3d38bee3c","stripe","pm_1PsSCYCJ5AfyAmaKo4RuyX6v","2024-09-10 10:04:27.018267" "fe2aaa36-d3fd-487a-8dfb-7735611a222e","stripe","pm_1PsSCBCJ5AfyAmaKNKtGoK0k","2024-09-10 10:04:34.842439" "d1717e32-1324-4933-962f-0da7b21eebee","stripe","pm_1PsSC5CJ5AfyAmaKZoxU2bzz","2024-09-10 10:04:36.802841" "a7ac16ab-a519-4986-931c-3d328fc8329f","stripe","pm_1PsSCOCJ5AfyAmaKudXbrJRE","2024-09-10 10:04:30.382309"