Skip to main content
If you want to use Commerce as an orchestration and abstraction layer but continue to process your payments directly with your acquirer, you can use our standalone authentication API. This enables you to only authenticate payments. Commerce will not process the subsequent authorization. Commerce supports Customer Initiated and Merchant Initiated (3RI) authentications.

​
Customer initiated

Your customer is online with your experience and you are ready to authenticate a payment. The prerequisite for such an operation is the presence of a Commerce token. This token is created by the Tokens API and contains all the necessary information to authenticate a payment. There are two types of these customer initiated authentications:
  1. One-off - A single one-off payment situation.
  2. Initial Recurring - The first payment in a series of recurring payments.

​
One-off

​
Request for a 60 EUR payment

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": 6000,
    "currency_code": "EUR",
    "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39"
  }'
Find the API Specification for more details about the various request parameters.

​
Response example

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
  },
  "amount": 6000,
  "currency_code": "EUR",
  "status": "PROCESSING",
  "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39",
  "type": "ONE_OFF"
}
Use one of our SDKs to process the action requirement. See the API reference for more information. You will be informed via a webhook about the result of the authentication. For demonstrations we show an exemplary response from the authentication management API. 
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "amount": 6000,
  "authentication_result": {
    "cardholder_data": {
      "authentication_value": "eNrNV1mTqsgSfvdXdJx5ZOawC56gjSgWFZUdQXhjkx0UkMVff2md6dM..=",
      "ds_transaction_id": "746753a1-2c4d-4396-a1ed-4003e63c7e15",
      "eci": "05"
    },
    "encrypted_token_data": "..."
  },
  "currency_code": "EUR",
  "status": "COMPLETED",
  "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39",
  "type": "ONE_OFF"
}
In case the Commerce token was backed by a network token, you also get the associated token authentication value (TAVV) as encrypted_token_data in the response. It is encrypted using the merchant’s encryption key.

​
Initial recurring

This is the first payment in a row of recurring payments and requires a customer be present as well (API Reference). The process of running such type of authentication is similar to the one described above. The authentication is requested on /authentications/recurring and requires a slightly different set of parameters: 
{
  "amount": 6000,
  "currency_code": "EUR",
  "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39",
  "recurring_expiry": 20281231,
  "recurring_frequency": 28
}
The request requires the recurring_frequency, which is the minimal amount of days to be expected between two authentications, and the recurring_expiry date of the recurring series.
Any further authentication will be able to authenticate at max up to the amount of the initial authentication.

​
Merchant initiated (3RI)

These calls support the processing of re-authentications directly by the requestor. They are meant to be running without the need for customer interactions and can be considered to be merchant initiated in this sense.
Merchant Initiated Authentication (3RI) are not yet widely supported by the card schemes.In order to use 3RI, you need to check-in with our support team to enable this feature for your account.

​
Subsequent recurring

Subsequent recurring payments can be re-authenticated with 3RI. They require an initial authentication and are executed in the context of such a transaction (see API Reference).

​
Rules

  • The frequency must be taken into account
  • The amount must be less or equal to the amount of the initial authentication
  • The authentication must not be requested after the expiry date