Authenticate a payment using credentials on file (COF).
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).
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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
curl -i -X POST \
https://sandbox.hellgate.io/authentications/cof \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
"amount": 0,
"currency_code": "string",
"token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39"
}'Success response
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 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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
The three letter currency code. See: ISO-4217
The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.
The reasons why an authentication failed during processing in Hellgate.
The ID of the original authentication in case of subsequent authentications
Indicates the maximum number of authorisations permitted for installment payments.
The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "action_requirement": { "type": "redirect", "target_url": "http://example.com", "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82" }, "amount": 0, "authentication_result": { "cardholder_data": { … }, "encrypted_token_data": "string" }, "challenge_preference": "CHALLENGE", "created_at": "string", "currency_code": "string", "recurring_expiry": "string", "recurring_frequency": 0, "failure_details": [ { … } ], "finished_at": "string", "original_authentication": "39771284-fecf-4f85-afe9-965a8187a1e2", "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea", "number_of_installments": 0, "purchase_date": "string", "status": "PROCESSING", "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39", "type": "COF_PAYMENT" }
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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
The date when the recurring should expiry. Requires the format yyyyMMdd.
curl -i -X POST \
https://sandbox.hellgate.io/authentications/recurring \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
"amount": 0,
"currency_code": "string",
"recurring_expiry": "string",
"recurring_frequency": 0,
"token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39"
}'Authentication created
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 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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
The three letter currency code. See: ISO-4217
The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.
The reasons why an authentication failed during processing in Hellgate.
The ID of the original authentication in case of subsequent authentications
Indicates the maximum number of authorisations permitted for installment payments.
The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "action_requirement": { "type": "redirect", "target_url": "http://example.com", "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82" }, "amount": 0, "authentication_result": { "cardholder_data": { … }, "encrypted_token_data": "string" }, "challenge_preference": "CHALLENGE", "created_at": "string", "currency_code": "string", "recurring_expiry": "string", "recurring_frequency": 0, "failure_details": [ { … } ], "finished_at": "string", "original_authentication": "39771284-fecf-4f85-afe9-965a8187a1e2", "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea", "number_of_installments": 0, "purchase_date": "string", "status": "PROCESSING", "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39", "type": "COF_PAYMENT" }
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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
Indicates the maximum number of authorisations permitted for installment payments.
The date when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
The date when the recurring should expire. Requires the format yyyyMMdd.
curl -i -X POST \
https://sandbox.hellgate.io/authentications/installment \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
"amount": 0,
"currency_code": "string",
"number_of_installments": 0,
"recurring_expiry": "string",
"recurring_frequency": 0,
"token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39"
}'Authentication created
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 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 preference with respect to an eventual challenge.
There is no guarantee that the preference can be fulfilled.
The three letter currency code. See: ISO-4217
The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.
The reasons why an authentication failed during processing in Hellgate.
The ID of the original authentication in case of subsequent authentications
Indicates the maximum number of authorisations permitted for installment payments.
The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "action_requirement": { "type": "redirect", "target_url": "http://example.com", "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82" }, "amount": 0, "authentication_result": { "cardholder_data": { … }, "encrypted_token_data": "string" }, "challenge_preference": "CHALLENGE", "created_at": "string", "currency_code": "string", "recurring_expiry": "string", "recurring_frequency": 0, "failure_details": [ { … } ], "finished_at": "string", "original_authentication": "39771284-fecf-4f85-afe9-965a8187a1e2", "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea", "number_of_installments": 0, "purchase_date": "string", "status": "PROCESSING", "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39", "type": "COF_PAYMENT" }