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.

Beta Features

Hellgate® offers various features as part of our beta release track. These features are clearly labeled with a Beta badge in the documentation and interface.

By default, accounts do not have access to beta features unless explicitly subscribed to beta releases. If you would like to enable beta features, please contact your account manager for subscription options.

⚠️ Beta features are experimental and subject to change or removal at any time. They may also have limited support and stability.

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

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.

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:

ParameterTypeDescription
limitintegerThe maximum amount of objects to be returned on a page.
pageintegerThe requested number of the page to return.

Request Errors

Hellgate® uses the standard errors to indicate the client errors on the gateway level.

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..."
}

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
Overview
Languages
Servers
Hellgate® Sandbox
https://sandbox.hellgate.io/
Hellgate® Production
https://api.hellgate.io/

Customer Initiated

Operations

Payment Modifications

Operations

Payment Data

Operations

Customer Initiated

Hellgate® allows to process EMVCo 3-D Secure authentication requests as standalone request.

For example, these endpoints can be used to process payment authentication centrally and process the subsequent authorization requests conditionally on different payment processors.

The secion of customer initiated authentications consists of three use-cases:

Use-Case Description
One OffA standard situation in which a single payment amount shall undergo 3-D Secure authentication.
Initial RecurringAn authentication of the first payment in the sequence of recurring payments.
Initial InstallmentAn authentication of the first payment in the sequence of installment payments.
Operations

Merchant Initiated (3RI)

Hellgate® supports requestor-initiated EMVCo 3-D Secure authentication requests as standalone transactions.

All requests in this section must be linked to a prior customer-initiated authentication.

Operations

Authentication Data

Access the results of prior authentications for reference.

Operations

Credentials on File

Operations

Create Hellgate® Tokens

Hellgate® Tokens are powerful instrument to manage card holder data in a PCI/DSS compliant way.

Compliance as a Service

Achieve PCI / DSS compliance in almost no time using our certified managed compliance service.

No Acquirer Lock-In

Transparently use the cardholder data across all connected processors to implement a non lock-in acquiring setup.

Network Tokens

For every card which is tokenized on Hellgate®, network-tokens can be automatically provisioned. This allows for more secure transactions, better conversion, and ultimately lower processing cost.

Operations

Token Management

All cards stored with Hellgate® can be managed via the endpoints in this section.

The CVC2 security code is only kept in an ephemeral cache for a few minutes. The API allows to manage this resource with these endpoints:

  • check if the CVC2 is still availble
  • request a new session to renew the CVC2 with our SDK
  • consume the token after a successful authorization on an external processor
Operations

Network Tokens

Hellgate® supports Network Tokens with major card schemes.

The lifecycle of network tokens is automatically managed. When activated a network token is automatically provisioned and maintained through its life-cycle.

The use of Network Tokens requires prior activation by your account manager.

Operations

Compliance Service

Operations

Merchants

Hellgate® accounts support two operating models.

This is the default model for accounts.

  • It is not possible to add sub-merchants (via POST /merchants)
  • It is not possible to delete the primary merchant (via DELETE /merchants/{id})
Operations

Create a merchant

Request

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.

Bodyapplication/json
company_citystringrequired

The city in the merchant's primary address.

Example: "Berlin"
country_codestringrequired
legal_namestringrequired

The name of the merchant

Example: "Example Merchant"
website_urlstring(uri)required

The URL of the merchant's website

Example: "https://example.com"
identity_and_verification_enabledboolean

The flag indicates if the 3DS identity and verification is required or not (only allowed for primary)

3ds_enabledboolean

Indicates if 3DS is available or not for the Merchant

Example: true
default_currencystring

The three letter currency code. See: ISO-4217

default_merchant_idstring

The id for the Merchant

Example: 1234567890
schemesArray of objects

The schemes supported by the merchant (required if merchant has a merchant_id)

Example: {"name":"visa","acquirer_bin":40001,"requestor_id":"123456789.visa","requestor_name":"3dsclient.local.visa","category_code":3200,"merchant_id":"","merchant_name":""}
curl -i -X POST \
  https://sandbox.hellgate.io/merchants \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "company_city": "Berlin",
    "country_code": "DE",
    "legal_name": "Example Merchant",
    "website_url": "https://example.com",
    "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": ""
    }
  }'

Responses

Success response

Bodyapplication/json
idstring(uuid)required

The ID of the merchant

Example: "00000000-0000-0000-0000-000000000000"
created_atstring(date-time)required

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

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

The city in the merchant's primary address.

Example: "Berlin"
country_codestringrequired
encryption_keystringrequired

The key used to encrypt authentication data (for instance network token and cryptogram). This information is returned only once, when the merchant was initially created. Subsequent calls will return a masked value.

Example: "eyJhbGciOiJSUzI1NiIsImVudGl0bGVtZW50IjoiYWF4NXdq..."
legal_namestringrequired

The name of the merchant

Example: "Example Merchant"
website_urlstring(uri)required

The URL of the merchant's website

Example: "https://example.com"
Response
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

Request

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

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.

sortstring

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

fromstring(date-time)

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

tostring(date-time)

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

country_codestring

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

curl -i -X GET \
  'https://sandbox.hellgate.io/merchants?country_code=string&from=2019-08-24T14%3A15%3A22Z&limit=1&page=1&sort=string&to=2019-08-24T14%3A15%3A22Z' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Success response

Bodyapplication/json
dataArray of objects
Example: [{"id":"9071cd4e-9627-421b-96cc-d48ffda5e894","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","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":""}]}]
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 merchant details

Request

Get the information of a merchant.

Path
idstring(uuid)required

The ID of the merchant

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

Responses

Success response

Bodyapplication/json
idstring(uuid)required

The ID of the merchant

Example: "9071cd4e-9627-421b-96cc-d48ffda5e894"
created_atstring(date-time)required

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

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

The city in the merchant's primary address.

Example: "Berlin"
country_codestringrequired
encryption_keystringrequired

The masked version of the key used to encrypt authentication data (for instance network token and cryptogram). A full copy of this information is returned only once, when the merchant was initially created.

Example: "eyJhbGciO[redacted]"
legal_namestringrequired

The name of the merchant

Example: "Example Merchant"
website_urlstring(uri)required

The URL of the merchant's website

Example: "https://example.com"
typestringrequired

The merchant type

Enum"primary""submerchant"
Example: "submerchant"
identity_and_verification_enabledboolean

The flag indicates if the 3DS identity and verification is required or not (only allowed for primary)

3ds_enabledboolean

Indicates if 3DS is available or not for the Merchant

Example: true
default_currencystring

The three letter currency code. See: ISO-4217

default_merchant_idstring

The id for the Merchant

Example: "1234567890"
schemesArray of objects

The schemes supported by the merchant (required if merchant has a merchant_id)

Example: [{"name":"visa","acquirer_bin":"40001","requestor_id":"123456789.visa","requestor_name":"3dsclient.local.visa","category_code":"3200","merchant_id":"","merchant_name":""}]
Response
application/json
{ "id": "9071cd4e-9627-421b-96cc-d48ffda5e894", "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", "type": "submerchant", "identity_and_verification_enabled": false, "3ds_enabled": true, "default_currency": "EUR", "default_merchant_id": "1234567890", "schemes": [ {} ] }

Update merchant

Request

Update the information of a merchant.

Path
idstring(uuid)required

The ID of the merchant

Bodyapplication/json
company_citystringrequired

The city in the merchant's primary address.

country_codestringrequired
legal_namestringrequired

The name of the merchant

website_urlstring(uri)required

The URL of the merchant's website

identity_and_verification_enabledboolean

The flag indicates if the 3DS identity and verification is required or not (only allowed for primary)

3ds_enabledboolean

Indicates if 3DS is available or not for the Merchant

default_currencystring

The three letter currency code. See: ISO-4217

default_merchant_idstring

The id for the Merchant

schemesArray of objects

The schemes supported by the merchant (required if merchant has a merchant_id)

curl -i -X PATCH \
  'https://sandbox.hellgate.io/merchants/{id}' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "company_city": "string",
    "country_code": "string",
    "legal_name": "string",
    "website_url": "http://example.com"
  }'

Responses

Success response

Bodyapplication/json
idstring(uuid)required

The ID of the merchant

Example: "9071cd4e-9627-421b-96cc-d48ffda5e894"
created_atstring(date-time)required

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

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

The city in the merchant's primary address.

Example: "Berlin"
country_codestringrequired
encryption_keystringrequired

The masked version of the key used to encrypt authentication data (for instance network token and cryptogram). A full copy of this information is returned only once, when the merchant was initially created.

Example: "eyJhbGciO[redacted]"
legal_namestringrequired

The name of the merchant

Example: "Example Merchant"
website_urlstring(uri)required

The URL of the merchant's website

Example: "https://example.com"
typestringrequired

The merchant type

Enum"primary""submerchant"
Example: "submerchant"
identity_and_verification_enabledboolean

The flag indicates if the 3DS identity and verification is required or not (only allowed for primary)

3ds_enabledboolean

Indicates if 3DS is available or not for the Merchant

Example: true
default_currencystring

The three letter currency code. See: ISO-4217

default_merchant_idstring

The id for the Merchant

Example: "1234567890"
schemesArray of objects

The schemes supported by the merchant (required if merchant has a merchant_id)

Example: [{"name":"visa","acquirer_bin":"40001","requestor_id":"123456789.visa","requestor_name":"3dsclient.local.visa","category_code":"3200","merchant_id":"","merchant_name":""}]
Response
application/json
{ "id": "9071cd4e-9627-421b-96cc-d48ffda5e894", "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", "type": "submerchant", "identity_and_verification_enabled": false, "3ds_enabled": true, "default_currency": "EUR", "default_merchant_id": "1234567890", "schemes": [ {} ] }

Delete a merchant

Request

Remove a merchant from Hellgate.

Warning

This operation cannot be undone.

Path
idstring(uuid)required

The ID of the merchant

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

Responses

Success response (No Content)

Response
No content

Processor Backup

In case your precious payment-method data is currently locked into an acquirer processor, Hellgate® allows you to migrate the tokens automatically. Currently we support stripe.com, but more processors are on our list. Please ask you account manager for more information.

Detailed documentation on how to migrate your stripe payment methods can be found on the Hellgate® Developer Documentation.

Operations

Reconciliation

Operations