# Commerce API 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 Version: 2.0 License: Hellgate API Terms ## Servers Hellgate Sandbox ``` https://sandbox.hellgate.io ``` Hellgate Production ``` https://api.hellgate.io ``` ## Security ### APIKeyAuth Type: apiKey In: header Name: X-API-Key ## Download OpenAPI description [Commerce API](https://api-reference.hellgate.io/_spec/products/commerce/openapi.yaml) ## 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. ### One-off - [POST /payments/one-off](https://api-reference.hellgate.io/products/commerce/openapi/payments_ci/request_one_off_payment.md): Request a one-off payment. This API endpoint is used to initiate a one-time payment that requires the customer to be actively on-session. These payments involve real-time customer interactions and are the primary method for customer-initiated payments. 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. ### Initial unscheduled - [POST /payments/unscheduled](https://api-reference.hellgate.io/products/commerce/openapi/payments_ci/request_initial_unscheduled_payment.md): 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. ### Initial recurring - [POST /payments/recurring](https://api-reference.hellgate.io/products/commerce/openapi/payments_ci/request_initial_recurring_payment.md): 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 date must not be exceeded. - Frequency Compliance: The must not be lower than the defined minimum. - Amount Restriction: The must not exceed the initially authorized amount. 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. ## 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. ### Unscheduled - [POST /payments/unscheduled/{id}/subsequent](https://api-reference.hellgate.io/products/commerce/openapi/payments_mi/request_subsequent_unscheduled_payment.md): Request a subsequent unscheduled payment. - The customer does not need to be on-session for this payment. - If 3RI is enabled on the account, the payment request can include an off-session authentication initiated by the requestor. ### Recurring - [POST /payments/recurring/{id}/subsequent](https://api-reference.hellgate.io/products/commerce/openapi/payments_mi/request_subsequent_recurring_payment.md): Request a subsequent recurring payment. - The customer does not need to be on-session for this payment. - If 3RI is enabled on the account, the payment request can include an off-session authentication initiated by the requestor. The request must to follow the schedule defined by the initial recurring payment. ## 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. ### Capture - [POST /payments/{id}/capture](https://api-reference.hellgate.io/products/commerce/openapi/payments_modifications/capture_payment.md): Attempts to capture a payment that is currently in authorized. The attributes and are optional. If not provided, the full authorized amount will be captured. If a partial amount is provided, it must be less than or equal to the authorized amount and the currency must match the authorized amount. The operation is asynchronous such that the result will be communicated via a notifcation. ### Void - [POST /payments/{id}/void](https://api-reference.hellgate.io/products/commerce/openapi/payments_modifications/cancel_payment.md): 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. ### Refund - [POST /payments/{id}/refunds](https://api-reference.hellgate.io/products/commerce/openapi/payments_modifications/create_refund.md): Request a refund for a payment. This API endpoint is used to initiate a refund for a payment that has been successfully captured. Refunds can be in full or partial. Depending on the payment method, the refund may take a few days to be processed. ## 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 ### Get payments - [GET /payments](https://api-reference.hellgate.io/products/commerce/openapi/payments_data/list_payments.md): Retrieves a paginated list of payments associated with the account. Payments are sorted in reverse chronological order (most recent first). The caller can specify the number of payments per page using a query parameter, with a maximum limit of 500 payments per page. If no value is provided, a default number of payments per page will be used. ### Get payment details - [GET /payments/{id}](https://api-reference.hellgate.io/products/commerce/openapi/payments_data/get_payment.md): Returns the details of the payment with the specified identifier. ### List transactions - [GET /payments/{id}/transactions](https://api-reference.hellgate.io/products/commerce/openapi/payments_data/list_payment_transactions.md): Retrieves a paginated list of all transactions associated with a payment. The results are grouped into pages, and the caller can specify the number of transactions per page via a query parameter, with a maximum limit of 500 transactions per page. If no value is specified, a default page size will be used. ### Get refunds - [GET /payments/{id}/refunds](https://api-reference.hellgate.io/products/commerce/openapi/payments_data/list_refunds_of_payment.md): Get a list of all refunds that belong to a payment. ## 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 ### Get refund details - [GET /refunds/{id}](https://api-reference.hellgate.io/products/commerce/openapi/refunds_data/get_a_refund.md): Get the details of a refund. ### List transactions - [GET /refunds/{id}/transactions](https://api-reference.hellgate.io/products/commerce/openapi/refunds_data/list_refund_transactions.md): Retrieves a paginated list of all transactions associated with a refund. The results are grouped into pages, and the caller can specify the number of transactions per page via a query parameter, with a maximum limit of 500 transactions per page. If no value is specified, a default page size will be used. ## 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: {% table %} - Use-Case {% width="30%" %} - 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. {% /table %} ### One-off - [POST /authentications/one-off](https://api-reference.hellgate.io/products/commerce/openapi/authentications_ci/create_authentication_cof.md): 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. ### Initial recurring - [POST /authentications/recurring](https://api-reference.hellgate.io/products/commerce/openapi/authentications_ci/create_recurring_authentication.md): 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. ### Initial installment - [POST /authentications/installment](https://api-reference.hellgate.io/products/commerce/openapi/authentications_ci/create_installment_authentication.md): 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. ## 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. ### Subsequent recurring - [POST /authentications/recurring/{id}/subsequent](https://api-reference.hellgate.io/products/commerce/openapi/authentications_mi/create_subsequent_recurring_authentication.md): Authenticate for a subsequent recurring payment. This authentication is initiated by the requestor (3RI) and will not require interactions with customers; it can be run off-session. ### Subsequent installment - [POST /authentications/installment/{id}/subsequent](https://api-reference.hellgate.io/products/commerce/openapi/authentications_mi/create_installment_recurring_authentication.md): Authenticate for a subsequent installment payment. This authentication is initiated by the requestor (3RI) and will not require interactions with customers; it can be run off-session. ## Authentication Data Access the results of prior authentications for reference. ### Get authentications - [GET /authentications](https://api-reference.hellgate.io/products/commerce/openapi/authentications_data/get_authentications.md): Get a list of all the authentications for this account. The results are grouped into pages. The caller can specify how many customers per page shall be listed (maximum is 500). ### Get an authentication - [GET /authentications/{id}](https://api-reference.hellgate.io/products/commerce/openapi/authentications_data/get_authentications_detail.md): Return the details of an authentication referenced by its id ## 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 ### Get credentials - [GET /credentials](https://api-reference.hellgate.io/products/commerce/openapi/credentials_management/list_credentials.md): Get a list of credentials on file which 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). ### Get credential details - [GET /credentials/{id}](https://api-reference.hellgate.io/products/commerce/openapi/credentials_management/get_credential.md): Get the detail information about stored credentials. ### Delete credentials - [DELETE /credentials/{id}](https://api-reference.hellgate.io/products/commerce/openapi/credentials_management/remove_credentials.md): Remove a credentials from Hellgate. {% admonition type="info" name="Information" %} Hellgate only soft-deletes data. So in case of deletion this value will be anonymized. {% /admonition %} ## Create Hellgate Tokens Hellgate Tokens are powerful instrument to manage card holder data in a PCI/DSS compliant way. {% cards %} {% card title="Compliance as a Service" %} Achieve PCI / DSS compliance in almost no time using our certified managed compliance service. {% /card %} {% card title="No Acquirer Lock-In" %} Transparently use the cardholder data across all connected processors to implement a non lock-in acquiring setup. {% /card %} {% card title="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. {% /card %} {% /cards %} ### Request a token session - [POST /tokens/session](https://api-reference.hellgate.io/products/commerce/openapi/tokens_create/create_tokenization_session.md): Create a session to start Hellgate Tokenization using our SDK. ### Create token from FPAN - [POST /cde-import](https://api-reference.hellgate.io/products/commerce/openapi/tokens_create/import_cardholder_data.md): Import cardholder-data in exchange for a Hellgate token. {% admonition type="warning" name="Compliance Check Required" %} In order to use this endpoint you need to prove a certain level of compliance with PCI/DSS with us. Reach out to your account manager for more information. {% /admonition %} ## 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 ### Get tokens - [GET /tokens](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/list_tokenized_cards.md): Get a list of all Hellgate tokens 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). ### Get token details - [GET /tokens/{id}](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/get_tokenized_card.md): Get a Hellgate token by its identifer. ### Delete a token - [DELETE /tokens/{id}](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/remove_tokenized_card.md): Remove a Hellgate token and all associated information (e.g. network tokens). {% admonition type="warning" name="Warning" %} This operation cannot be undone. {% /admonition %} ### Check CVC2 - [GET /tokens/{id}/security-code](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/get_tokenized_card_security_information.md): Get an indicator if security information for a stored Hellgate token is still available. ### Refresh CVC2 - [POST /tokens/{id}/refresh-session](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/refresh_secutiry_token_session.md): Create a session to update the Security Code from a Hellgate Token using our SDK. ### Consume a token - [POST /tokens/{id}/consume](https://api-reference.hellgate.io/products/commerce/openapi/tokens_management/consume_security_code.md): Tell Hellgate after successful use of the token for an payment authorization, that the CVC2 can be removed from cache. ## 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 ### Forward card data - [POST /forward](https://api-reference.hellgate.io/products/commerce/openapi/compliance_service/forward_request.md): This endpoint allows to securely forward cardholder data to a certified third-party provider. It will inject sensitive cardholder data, referenced by a Hellgate token, into the request before forwarding it. Hellgate requires certain HTTP headers for this feature. These headers are reserved and cannot be used by the caller: {% table %} - Header {% width="30%" %} - Required - Description --- - - Yes - Authentication of the request. --- - - Yes - Identify the Hellgate token to use for the request. --- - - Yes - Define the target URL to which the request shall be forwarded. --- - - No - Define the API version to use for the request. {% /table %} Refer to the general documentation about forwarding senstive data for more information. ## 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. {% admonition type="info" %} The use of Network Tokens requires prior activation by your account manager. {% /admonition %} ### Update a network token - [POST /tokens/{id}/provisions](https://api-reference.hellgate.io/products/commerce/openapi/network_tokens/network_token_provision.md): If the provisioning of a network token status is or for any reason, this endpoint can be used to provision a network token. ### Request payment-data - [POST /tokens/{id}/payment-data](https://api-reference.hellgate.io/products/commerce/openapi/network_tokens/request_payment_data.md): Request a payment-data bundle for a Hellgate token. The bundle can contain various elements including the TAVV cryptogram for a network token. {% admonition type="info" %} This call supports the all operating models of Hellgate ( and ). For eco-systems you need to specify which merchant you want to request the crypotgram for. {% /admonition %} ### Get payment-data - [GET /tokens/{id}/payment-data](https://api-reference.hellgate.io/products/commerce/openapi/network_tokens/list_payment_data.md): List all payment-data bundles created for this Hellgate Token. ### Forward payment-data - [POST /payment-data/{id}/forward](https://api-reference.hellgate.io/products/commerce/openapi/network_tokens/forward_payment_data.md): This endpoint enables platform merchants to leverage payment-data bundles in their acquirer integration. The request is forwarded to the configured destination URL of your merchant settings. Hellgate requires certain HTTP headers for this feature. These headers are reserved and cannot be used by the caller: {% table %} - Header {% width="30%" %} - Required - Description --- - - Yes - Authentication of the request. --- - - No - Define the API version to use for the request. {% /table %} Refer to the general documentation about forwarding senstive data for more information. ## 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. {% tabs %} {% tab label="Primary Merchant" %} 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 {% /tab %} {% tab label="Platform / Marketplace" %} Enable multiple sellers or service providers to process payments through your platform. - Add and manage multiple sub-merchants - Configure individual processing rules per merchant - Track transactions by merchant for split payments - Implement marketplace payment flows {% admonition type="info" %} Platform model requires activation by your account manager. {% /admonition %} {% /tab %} {% tab label="Ecosystem" %} Grant controlled payment capabilities to third parties within your business ecosystem. - Onboard ecosystem partners as sub-merchants - Set transaction limits and permissions per partner - Maintain oversight of all ecosystem transactions - Common in mobility, delivery, and service networks {% admonition type="info" %} Ecosystem model requires validation of your use case by your account manager. {% /admonition %} {% /tab %} {% tab label="Managed Ecosystem" %} Full payment facilitation with comprehensive merchant management capabilities. - Advanced sub-merchant onboarding and underwriting - Risk management and compliance tools - Detailed merchant monitoring and reporting - Support for complex multi-party payment flows {% admonition type="warning" %} Managed Ecosystem requires special licensing and compliance review. {% /admonition %} {% /tab %} {% /tabs %} ### Create a merchant - [POST /merchants](https://api-reference.hellgate.io/products/commerce/openapi/merchants/onboard_merchant.md): 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. ### Get merchants - [GET /merchants](https://api-reference.hellgate.io/products/commerce/openapi/merchants/list_merchants.md): 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). ### Get merchant details - [GET /merchants/{id}](https://api-reference.hellgate.io/products/commerce/openapi/merchants/get_merchant.md): Get the information of a merchant. ### Update merchant - [PATCH /merchants/{id}](https://api-reference.hellgate.io/products/commerce/openapi/merchants/update_merchant.md): Update the information of a merchant. ### Delete a merchant - [DELETE /merchants/{id}](https://api-reference.hellgate.io/products/commerce/openapi/merchants/remove_merchant.md): Remove a merchant from Hellgate. {% admonition type="warning" name="Warning" %} This operation cannot be undone. {% /admonition %} ## 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](https://developer.hellgate.dev/resources/imports/backup_stripe). ### Request a token import - [POST /tokens/imports](https://api-reference.hellgate.io/products/commerce/openapi/processor_backup/tokens_import.md): Requests the import of cardholder data from a third-party vault (currently supported source is stripe.com). The import processed in the background and its status can be queried by the returned import ID. During preparation and processing of a job it is not possible to create another import. ### Get import details - [GET /tokens/imports/{id}](https://api-reference.hellgate.io/products/commerce/openapi/processor_backup/get_tokens_details.md): Show details of a token import ### Abort an import - [POST /tokens/imports/{id}/abort](https://api-reference.hellgate.io/products/commerce/openapi/processor_backup/tokens_import_abort.md): Abort a running token import. This is possible while the import is not finished or already aborted. ### Get import failures - [GET /tokens/imports/{id}/failures](https://api-reference.hellgate.io/products/commerce/openapi/processor_backup/get_token_import_failures.md) ## Reconciliation Reconcile imported token data. ### Token Import Report - [GET /reports/tokens](https://api-reference.hellgate.io/products/commerce/openapi/reconciliation/tokens_report.md): This report gives allowes to reconcile imported tokens from third-party sources. The report contains all Hellgate tokens of the current account. The tokens are annotated with a and the corresponding (i.e. the ID of the cardholder data at the provider).