Initial recurring

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

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.

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

openapi.json

openapi.yaml

Overview

URL https://hellgate.io

Starfish GmbH & Co. KG hello@starfish.team

License Hellgate® API Terms

Servers

Hellgate® Sandbox

https://sandbox.hellgate.io/

Hellgate® Production

https://api.hellgate.io/

Customer Initiated

Operations

Initial unscheduledBeta

Request

Request the initial payment for unscheduled subsequent payments.

This API endpoint is used to initiate an initial payment that requires the customer to be actively on-session. With the payment successfully authorized, subsequent unscheduled payments can be made while the customer is off-session.

Hellgate® utilizes an action_requirement mechanism to prompt any necessary customer interactions during the payment process. The interactions are supported with SDKs. See the Hellgate Developer Documentation for more information.

Bodyapplication/json

additional_informationobject

amountinteger>= 0required

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_codestringrequired

The three letter currency code. See: ISO-4217

referencestring<= 80 charactersrequired

A description of the payment for later reference

sourceany

The source for this initial payment.

Type	Description
checkout	During the checkout an action requirement will be available, to determine the actual payment credentials from the shopper. The SDKs can be used to handle the session and safely process the payment data.
token	An already existing Hellgate® token can be used as source for the payment.
credential	Already stored credentials are used as source for the payment.

Default "checkout"

curl -i -X POST \
  https://sandbox.hellgate.io/payments/unscheduled \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "currency_code": "EUR",
    "reference": "Order #12345",
    "source": {
      "type": "checkout"
    }
  }'

Responses

Success response

Bodyapplication/json

idstring(uuid)required

The ID of the payment on Hellgate®

action_requirementobject

additional_informationobject

authentication_preferencestring

The preference for the authentication method to be used for the payment.

Preference	Description
NO_3RI	Don't perform 3RI authentication for this payment (Default).
TRY_3RI	Try to perform 3RI authentication for this payment. If it fails the payment will still be sent for authorization.
REQUIRE_3RI	Require 3RI authentication for this payment. If it fails the payment will not be sent for authorization.

Default "NO_3RI"

Enum"NO_3RI""TRY_3RI""REQUIRE_3RI"

authentication_resultobject

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

amountobjectrequired

amount.requestedinteger>= 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.

amount.authorizedinteger>= 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.

amount.capturedinteger>= 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.

amount.voidedinteger>= 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.

amount.refundedinteger>= 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.

created_atstring(date-time)required

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

currency_codestringrequired

The three letter currency code. See: ISO-4217

credential_idstring(uuid)

The ID of the credential associated with the payment.

failure_detailsArray of objects

The reasons why a payment failed during processing in Hellgate.

This can be due to 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.

flow_matrix_rulestring

The rule in the flow matrix, which was chosen to process the payment.

initial_payment_idstring(uuid)

The ID of the initial payment.

Only present for subsequent merchant-initiated payments.

processing_annotationsobject

This is an optional attribute holding results from eventual pre-processing of the request.

referencestring<= 80 charactersrequired

A description of the payment for later reference

recurring_expirystring(yyyyMMdd)

The date when the recurring should expiry.

Only present for recurring payments.

recurring_frequencyinteger

Indicates the minimum number of days between authorisations.

Only present for recurring payments.

sourceany

The source that was used for the payment.

Type	Description
`card`	The payment method `card` was used as source

statusstringrequired

Enum"open""processing""failed""authorized""capturing""captured""settling""settled""voiding""voided"

use_casestringrequired

Definition of the payment use-case for processing

Enum"ONE_OFF""UNSCHEDULED""SUBSEQUENT_UNSCHEDULED""RECURRING""SUBSEQUENT_RECURRING"

Response

application/json

{
  "id": "54ba1fdb-7e4e-402b-aebb-66f9d5345cf8",
  "amount": {
    "requested": 1000
  },
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "currency_code": "EUR",
  "reference": "Order #12345",
  "status": "processing",
  "use_case": "UNSCHEDULED"
}

Callbacks

Payment Notification callback

post

Initial recurringBeta

Request

Request the initial payment for recurring subsequent payments.

This API endpoint is used to initiate an initial payment that requires the customer to be actively on-session. With the payment successfully authorized, subsequent recurring payments can be made while the customer is off-session.

Recurring payments must adhere to a predefined schedule to be successfully processed.

The following conditions must be met:

Expiration Limit: The recurring_expiry date must not be exceeded.
Frequency Compliance: The recurring_frequency must not be lower than the defined minimum.
Amount Restriction: The amount must not exceed the initially authorized amount.

Bodyapplication/json

additional_informationobject

amountinteger>= 0required

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_codestringrequired

The three letter currency code. See: ISO-4217

referencestring<= 80 charactersrequired

A description of the payment for later reference

recurring_expirystring(yyyyMMdd)required

The date when the recurring should expiry.

recurring_frequencyintegerrequired

Indicates the minimum number of days between authorisations.

sourceany

The source for this initial payment.

Type	Description
checkout	During the checkout an action requirement will be available, to determine the actual payment credentials from the shopper. The SDKs can be used to handle the session and safely process the payment data.
token	An already existing Hellgate® token can be used as source for the payment.
credential	Already stored credentials are used as source for the payment.

Default "checkout"

curl -i -X POST \
  https://sandbox.hellgate.io/payments/recurring \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "currency_code": "EUR",
    "reference": "Order #12345",
    "recurring_expiry": "20231010",
    "recurring_frequency": 28,
    "source": {
      "type": "checkout"
    }
  }'

Responses

Success response

Bodyapplication/json

idstring(uuid)required

The ID of the payment on Hellgate®

action_requirementobject

additional_informationobject

authentication_preferencestring

The preference for the authentication method to be used for the payment.

Preference	Description
NO_3RI	Don't perform 3RI authentication for this payment (Default).
TRY_3RI	Try to perform 3RI authentication for this payment. If it fails the payment will still be sent for authorization.
REQUIRE_3RI	Require 3RI authentication for this payment. If it fails the payment will not be sent for authorization.

Default "NO_3RI"

Enum"NO_3RI""TRY_3RI""REQUIRE_3RI"

authentication_resultobject

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

amountobjectrequired

amount.requestedinteger>= 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.

amount.authorizedinteger>= 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.

amount.capturedinteger>= 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.

amount.voidedinteger>= 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.

amount.refundedinteger>= 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.

created_atstring(date-time)required

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

currency_codestringrequired

The three letter currency code. See: ISO-4217

credential_idstring(uuid)

The ID of the credential associated with the payment.

failure_detailsArray of objects

The reasons why a payment failed during processing in Hellgate.

This can be due to 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.

flow_matrix_rulestring

The rule in the flow matrix, which was chosen to process the payment.

initial_payment_idstring(uuid)

The ID of the initial payment.

Only present for subsequent merchant-initiated payments.

processing_annotationsobject

This is an optional attribute holding results from eventual pre-processing of the request.

referencestring<= 80 charactersrequired

A description of the payment for later reference

recurring_expirystring(yyyyMMdd)

The date when the recurring should expiry.

Only present for recurring payments.

recurring_frequencyinteger

Indicates the minimum number of days between authorisations.

Only present for recurring payments.

sourceany

The source that was used for the payment.

Type	Description
`card`	The payment method `card` was used as source

statusstringrequired

Enum"open""processing""failed""authorized""capturing""captured""settling""settled""voiding""voided"

use_casestringrequired

Definition of the payment use-case for processing

Enum"ONE_OFF""UNSCHEDULED""SUBSEQUENT_UNSCHEDULED""RECURRING""SUBSEQUENT_RECURRING"

Response

application/json

{
  "id": "54ba1fdb-7e4e-402b-aebb-66f9d5345cf8",
  "amount": {
    "requested": 1000
  },
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "currency_code": "EUR",
  "reference": "Order #12345",
  "recurring_expiry": "20231010",
  "recurring_frequency": 28,
  "status": "processing",
  "use_case": "RECURRING"
}

Callbacks

Payment Notification callback

post

Merchant Initiated

Operations

Payment Modifications

Operations

Payment Data

Operations

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

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

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

Hellgate API (2.0)

Getting started

JSON Conventions

Authentication

API Use

API Versions

Idempotency

Pagination

Request Errors

Business Errors

Customer Initiated

Initial unscheduledBeta

RequestExpand all

Responses

Callbacks

Initial recurringBeta

RequestExpand all

Responses

Callbacks

Merchant Initiated

Payment Modifications

Payment Data

Refund Data

Customer Initiated

Merchant Initiated (3RI)

Authentication Data

Credentials on File

Create Hellgate® Tokens

Compliance as a Service

No Acquirer Lock-In

Network Tokens

Token Management

Network Tokens

Compliance Service

Merchants

Processor Backup

Reconciliation

Request

Request