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.
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.
id property.snake_case.null value instead.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® 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 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..."
}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).
Attempts to capture a payment that is currently in authorized.
Payments set to manual completion, and utilizing a payment method that supports manual capture, require a manual capture action to finalize the transaction. This process ensures that the payment is not automatically completed and provides additional control to the merchant or integration system to initiate the capture at the appropriate time.
The operation is asynchronous such that the result will be communicated via a notifcation.
curl -i -X POST \
'https://sandbox.hellgate.io/payments/{id}/capture' \
-H 'X-API-Key: YOUR_API_KEY_HERE'Capture accepted
The final result of the authentication. It holds in the cardholder authentication data (CAVV) and if there is a network token present, the token authentication data (TAVV).
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.
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.
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.
The three letter currency code. See: ISO-4217
The reasons why a payment failed during processing in Hellgate.
This can be due to an error in the consistency of the request as part of the confirmation of the payment, processing errors on the side of the processor, as well as errors in the processing of the underlying flow. In case the failure is due to a processing problem, the transaction history of the payment can give more information on the exact failure details.
The source that was used for the payment.
| Type | Description |
|---|---|
card | The payment method card was used as source |
{ "id": "54ba1fdb-7e4e-402b-aebb-66f9d5345cf8", "amount": { "requested": 1000, "authorized": 1000 }, "created_at": "2023-10-10T00:00:00Z", "currency_code": "EUR", "flow": "e-commerce flow", "reference": "Order #12345", "status": "capturing", "source": { "type": "card", "cardholder_name": "Bob Holder", "expiry_month": 12, "expiry_year": 2030, "masked_account_number": "424242XXXXXX4242", "pan_type": "FPAN" }, "use_case": "ONE_OFF" }
Attempts to void a payment.
Hellgate® will attempt to interrupt the payment processing and reverse the transaction. However, this operation may not always succeed due to limitations imposed by specific payment methods or providers. If the void operation is not possible, the payment will continue processing until it reaches its terminal state (e.g., successful completion or failure).
The operation is asynchronous such that the result will be communicated via a notifcation.
curl -i -X POST \
'https://sandbox.hellgate.io/payments/{id}/void' \
-H 'X-API-Key: YOUR_API_KEY_HERE'Cancel accepted
The final result of the authentication. It holds in the cardholder authentication data (CAVV) and if there is a network token present, the token authentication data (TAVV).
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.
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.
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.
The three letter currency code. See: ISO-4217
The reasons why a payment failed during processing in Hellgate.
This can be due to an error in the consistency of the request as part of the confirmation of the payment, processing errors on the side of the processor, as well as errors in the processing of the underlying flow. In case the failure is due to a processing problem, the transaction history of the payment can give more information on the exact failure details.
The source that was used for the payment.
| Type | Description |
|---|---|
card | The payment method card was used as source |
{ "id": "54ba1fdb-7e4e-402b-aebb-66f9d5345cf8", "amount": { "requested": 1000, "authorized": 1000 }, "created_at": "2023-10-10T00:00:00Z", "currency_code": "EUR", "flow": "e-commerce flow", "reference": "Order #12345", "status": "voiding", "source": { "type": "card", "cardholder_name": "Bob Holder", "expiry_month": 12, "expiry_year": 2030, "masked_account_number": "424242XXXXXX4242", "pan_type": "FPAN" }, "use_case": "ONE_OFF" }
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 Off | A standard situation in which a single payment amount shall undergo 3-D Secure authentication. |
| Initial Recurring | An authentication of the first payment in the sequence of recurring payments. |
| Initial Installment | An authentication of the first payment in the sequence of installment payments. |
Hellgate® Tokens are powerful instrument to manage card holder data in a PCI/DSS compliant way.
Achieve PCI / DSS compliance in almost no time using our certified managed compliance service.
Transparently use the cardholder data across all connected processors to implement a non lock-in acquiring setup.
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.
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:
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.
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.