Skip to main content
This reference is essential for your comprehensive understanding of Commerce V1 and successful integration with our event-driven payment processing platform. Commerce V1 APIs make use of RESTful conventions when possible. All calls use the standard HTTP verbs to express access semantics, like GET, POST, PATCH, and DELETE. The API is designed to work alongside CloudEvents for asynchronous service-to-service communication.

​
JSON Conventions

  • Resources are addressable by a UUIDv4 id property.
  • Property names are always in snake_case.
  • Commerce 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

Commerce V1 supports two authentication mechanisms to secure API access.

​
API Keys

API keys are passed via the HTTP header x-api-key for standard operations. 
curl --header 'x-api-key: <SECRET>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/...'

​
Mutual TLS (mTLS)

For service-to-service communication, particularly with extension services and processor integrations, Commerce V1 uses mutual TLS authentication over the event bridge. Both authentication methods 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

​
Cluster-based Deployment

Commerce V1 is provided as a service of the Hellgate Cloud Platform implementing the Composable Payment Architecture (CPA). Each instance is accessible via a cluster-specific URL: 
https://my-cluster-id.on-hellgate.cloud
Your specific cluster URL is provided during the onboarding process.

​
Idempotency

To prevent your system from handling requests twice and thus, for example, charging a customer twice, Commerce supports idempotency on requests to the API. The behavior is controlled via the header field X-Idempotency-Key. 
curl --header 'X-Idempotency-Key: <key>' \
  --request POST 'https://my-cluster-id.on-hellgate.cloud/...'

​
Pagination

Endpoints that return lists of objects support pagination. Commerce V1 uses page-based pagination with the following query parameters:
ParameterTypeDescription
limitintegerThe maximum amount of objects to be returned on a page.
pageintegerThe requested number of the page to return.
If an endpoint supports pagination, the response body follows this structure:
Response Sample
{
  "data": [...],
  "next_page": 2,
  "previous_page": null
}

​
Request Errors

Commerce uses standard HTTP status codes to indicate client errors on the API level.
The response payload for processing errors follows a standard format.
{
  "code": 404,
  "classifier": "not_found",
  "message": "The requested resource was not found"
}

​
Event-Driven Architecture

Commerce V1 uses CloudEvents 1.0 for asynchronous communication between services. Many operations trigger events that are delivered via the mTLS-secured event bridge. For detailed information about event types, payloads, and integration patterns, see the Eventing Reference.

​
Extension Services

Commerce V1 supports custom extension services that implement specific HTTP endpoints to extend payment processing flows. These services handle checkout experiences, 3-D Secure sessions, and SEPA mandate signatures. For information about implementing extension services, see the Extension Services documentation.