Skip to content
/Customer Initiated

Commerce API (2.0)

The Hellgate Commerce API provides a comprehensive payment orchestration platform designed to streamline and optimize payment processing for modern businesses. Built with flexibility and security at its core, our API enables you to process payments, manage authentications, and handle cardholder data across multiple payment processors without vendor lock-in.

Operating Models

Hellgate Commerce supports four distinct operating models to match your business needs:

  1. Primary Merchant - The standard operating model. Works great for single merchant setups.
  2. Platform - An operating model, which allows to process platform / marketplace payments.
  3. Ecosystem - An operationg model based on network tokens, which allows to facilitate transactions in e-commerce ecosystems.
  4. Managed Ecosystem - In this operating model, the management of the ecosystem is provided by Starfish as a service.

API Organization

The API is organized into logical groups:

  • Payments: Process and manage payment transactions
  • Authentications: Handle 3-D Secure authentication flows
  • Tokens: Create and manage payment tokens with network token support
  • Configuration: Manage merchants and account settings
  • Automation: Import existing tokens and generate reconciliation reports
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://hellgate.io

Starfish GmbH & Co. KG

hello@starfish.team

License

Hellgate API Terms

Languages
Servers
Hellgate Sandbox

https://sandbox.hellgate.io/

Hellgate Production

https://api.hellgate.io/

Customer Initiated

These endpoints handle payment processing where the customer is actively present and authorizing the transaction.

Supports multiple payment scenarios:

  • One-off payments: Single transactions for immediate purchase
  • Initial recurring: First payment in a subscription series with customer consent
  • Initial unscheduled: First payment for card-on-file scenarios

All customer-initiated payments optionally support 3-D Secure authentication for enhanced security.

Operations

Merchant Initiated

These transactions occur without direct customer interaction at the time of payment.

Key use cases:

  • Recurring subscriptions: Automated billing for subscription services
  • Unscheduled transactions: Variable charges based on usage or consumption
  • Retry logic: Re-attempt failed payments with stored credentials

All merchant-initiated payments must reference a prior customer-initiated transaction for compliance.

Operations

Payment Modifications

Modify existing payment transactions after initial authorization. Essential for flexible payment management across all operating models.

Available modifications:

  • Capture: Finalize pre-authorized payments (for two-step payment flows)
  • Void: Cancel authorized but uncaptured transactions
  • Refund: Return funds to customers for captured payments

Modifications can be applied across multiple processors, maintaining consistency in multi-processor setups.

Operations

Payment Data

Access comprehensive payment transaction data for reporting, reconciliation, and analysis. Critical for all operating models to maintain transaction visibility.

Features:

  • Transaction history: Full audit trail of payment lifecycle
  • Multi-processor visibility: Unified view across all connected processors
  • Real-time status: Current state of payments with processor responses
  • Filtering capabilities: Search and filter by multiple criteria
Operations

Refund Data

Access detailed refund transaction data for tracking and reconciliation. Essential for customer service and financial reporting across all operating models.

Provides:

  • Refund status tracking: Monitor refund processing across processors
  • Transaction linking: Connect refunds to original payments
  • Partial refund support: Track multiple refunds against single payments
  • Processor responses: Detailed feedback from payment processors
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

One-offBeta

Request

Request an authentication for a one-off payment.

This API endpoint triggers a 3-D Secure (3DS) authentication without processing a payment. It is used to verify a customer's identity before completing a transaction or for regulatory compliance (e.g., Strong Customer Authentication - SCA).

The customer must be on-session to complete the authentication. Hellgate utilizes the action_requirement mechanism to request any necessary interaction with the customer. The interactions are supported with SDKs. See the Hellgate Developer Documentation for more information.

Security
APIKeyAuth
Bodyapplication/json
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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
purchase_datestring

The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

curl -i -X POST \
  https://sandbox.hellgate.io/authentications/one-off \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "currency_code": "EUR",
    "source": {
      "type": "token",
      "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
    }
  }'

Responses

Success response

Bodyapplication/json
idstring(uuid)required

The ID of the authentication

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

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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
created_atstring(datetime)required

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

currency_codestringrequired

The three letter currency code. See: ISO-4217

recurring_expirystring

The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.

recurring_frequencyinteger

Indicates the minimum number of days between authentications.

failure_detailsArray of objects

The reasons why an authentication failed during processing in Hellgate.

finished_atstring(datetime)

The date-time the authentication was finished (following ISO 8601)

original_authenticationstring(uuid)

The ID of the original authentication in case of subsequent authentications

merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

number_of_installmentsinteger

Indicates the maximum number of authorisations permitted for installment payments.

purchase_datestring

The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

statusstringrequired
Enum"PROCESSING""COMPLETED""FAILED"
sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
use_casestringrequired
Enum"ONE_OFF""INITIAL_RECURRING""INITIAL_INSTALLMENT""SUBSEQUENT_RECURRING""SUBSEQUENT_INSTALLMENT"
Response
application/json
{
  "id": "7dcb4365-a948-4b41-a2d2-a7bffa2d3994",
  "amount": 1000,
  "currency_code": "EUR",
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "challenge_preference": "CHALLENGE",
  "purchase_date": "20241010000000",
  "use_case": "ONE_OFF",
  "source": {
    "type": "token",
    "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
  },
  "status": "PROCESSING"
}

Initial recurringBeta

Request

Request an authentication for an initial recurring payment.

This API endpoint triggers a 3-D Secure (3DS) authentication without processing a payment. It is used to verify a customer's identity before completing a transaction or for regulatory compliance (e.g., Strong Customer Authentication - SCA).

The customer must be on-session to complete the authentication. Hellgate utilizes the action_requirement mechanism to request any necessary interaction with the customer. The interactions are supported with SDKs. See the Hellgate Developer Documentation for more information.

Security
APIKeyAuth
Bodyapplication/json
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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
purchase_datestring

The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

recurring_expirystring(yyyyMMdd)required

The date when the recurring should expiry.

recurring_frequencyintegerrequired

Indicates the minimum number of days between authorisations.

sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

cardholder_informationobject
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": 1000,
    "currency_code": "EUR",
    "recurring_expiry": "20231231",
    "recurring_frequency": 28,
    "source": {
      "type": "token",
      "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
    }
  }'

Responses

Authentication created

Bodyapplication/json
idstring(uuid)required

The ID of the authentication

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

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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
created_atstring(datetime)required

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

currency_codestringrequired

The three letter currency code. See: ISO-4217

recurring_expirystring

The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.

recurring_frequencyinteger

Indicates the minimum number of days between authentications.

failure_detailsArray of objects

The reasons why an authentication failed during processing in Hellgate.

finished_atstring(datetime)

The date-time the authentication was finished (following ISO 8601)

original_authenticationstring(uuid)

The ID of the original authentication in case of subsequent authentications

merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

number_of_installmentsinteger

Indicates the maximum number of authorisations permitted for installment payments.

purchase_datestring

The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

statusstringrequired
Enum"PROCESSING""COMPLETED""FAILED"
sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
use_casestringrequired
Enum"ONE_OFF""INITIAL_RECURRING""INITIAL_INSTALLMENT""SUBSEQUENT_RECURRING""SUBSEQUENT_INSTALLMENT"
Response
application/json
{
  "id": "7dcb4365-a948-4b41-a2d2-a7bffa2d3994",
  "amount": 1000,
  "currency_code": "EUR",
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "purchase_date": "20241010000000",
  "recurring_expiry": "20231231",
  "recurring_frequency": 28,
  "use_case": "INITIAL_RECURRING",
  "source": {
    "type": "token",
    "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
  },
  "status": "PROCESSING"
}

Initial installmentBeta

Request

Request an authentication for an initial installment payment.

This API endpoint triggers a 3-D Secure (3DS) authentication without processing a payment. It is used to verify a customer's identity before completing a transaction or for regulatory compliance (e.g., Strong Customer Authentication - SCA).

The customer must be on-session to complete the authentication. Hellgate utilizes the action_requirement mechanism to request any necessary interaction with the customer. The interactions are supported with SDKs. See the Hellgate Developer Documentation for more information.

Security
APIKeyAuth
Bodyapplication/json
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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
number_of_installmentsintegerrequired

Indicates the maximum number of authorisations permitted for installment payments.

purchase_datestring

The date when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

recurring_expirystringrequired

The date when the recurring should expire. Requires the format yyyyMMdd.

recurring_frequencyintegerrequired

Indicates the minimum number of days between authorisations.

sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

cardholder_informationobject
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": 1000,
    "currency_code": "EUR",
    "recurring_expiry": "20231231",
    "recurring_frequency": 28,
    "number_of_installments": 12,
    "source": {
      "type": "token",
      "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
    }
  }'

Responses

Authentication created

Bodyapplication/json
idstring(uuid)required

The ID of the authentication

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

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

challenge_preferencestring

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Default "CHALLENGE"
Enum"CHALLENGE""NO_PREFERENCE""NO_CHALLENGE"
created_atstring(datetime)required

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

currency_codestringrequired

The three letter currency code. See: ISO-4217

recurring_expirystring

The date when the latest subsequent authentication can happen. Requires the format yyyyMMdd.

recurring_frequencyinteger

Indicates the minimum number of days between authentications.

failure_detailsArray of objects

The reasons why an authentication failed during processing in Hellgate.

finished_atstring(datetime)

The date-time the authentication was finished (following ISO 8601)

original_authenticationstring(uuid)

The ID of the original authentication in case of subsequent authentications

merchant_idstring(uuid)

The ID of the merchant for whom the authentication is requested

number_of_installmentsinteger

Indicates the maximum number of authorisations permitted for installment payments.

purchase_datestring

The data when the purchase was made. Requires the format yyyyMMddHHmmss and defaults to now.

statusstringrequired
Enum"PROCESSING""COMPLETED""FAILED"
sourceanyrequired

The payment credentials for this authentication request.

TypeDescription
tokenAn already existing Hellgate token can be used as source for the authentication.
Default "token"
source.​typestringrequired
Discriminator
source.​token_idstring(uuid)required
use_casestringrequired
Enum"ONE_OFF""INITIAL_RECURRING""INITIAL_INSTALLMENT""SUBSEQUENT_RECURRING""SUBSEQUENT_INSTALLMENT"
Response
application/json
{
  "id": "7dcb4365-a948-4b41-a2d2-a7bffa2d3994",
  "amount": 1000,
  "currency_code": "EUR",
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "challenge_preference": "CHALLENGE",
  "purchase_date": "20241010000000",
  "recurring_expiry": "20231231",
  "recurring_frequency": 28,
  "number_of_installments": 12,
  "use_case": "INITIAL_INSTALLMENT",
  "source": {
    "type": "token",
    "token_id": "71820e49-6822-4df1-8db5-d245456172b6"
  },
  "status": "PROCESSING"
}

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

Manage stored payment credentials for repeat customers across all operating models. Essential for subscription services, marketplaces, and ecosystems requiring seamless repeat transactions.

Capabilities:

  • Credential storage: Securely store customer payment methods for future use
  • Cross-processor portability: Use stored credentials with any connected processor
  • Compliance management: Automatic handling of card scheme mandates
  • Customer control: Enable customers to view and manage their stored payment methods
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

Compliance Service

Safely handle sensitive cardholder data while maintaining PCI DSS compliance across all operating models. Our compliance service acts as a secure proxy between your systems and payment processors.

Key features:

  • PCI DSS Level 1 certified: Reduce your compliance scope significantly
  • Data forwarding: Securely transmit cardholder data to processors without touching your systems
  • Format preservation: Maintain data formats required by different processors
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

Merchants

Configure and manage merchant accounts based on your chosen operating model. The merchant management capabilities adapt to support all four Hellgate Commerce operating models.

The default model for single businesses. Your account operates as a standalone merchant processing its own transactions.

  • Single merchant configuration locked to your primary account
  • Cannot add sub-merchants (POST /merchants disabled)
  • Cannot delete the primary merchant (DELETE /merchants/{id} disabled)
  • Full access to all payment features for your own transactions
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

Reconcile imported token data.

Operations
Starfish GmbH & Co. KG © 2025