Customer Initiated

This is the most common set of scenarios for authentication only payments. They are based on Hellgate's session protocol and are facilitated by our SDKs. The customer initiates the payment process and is guided through the authentication process by our SDKs.

Standard Credentials-on-File (COF)

You faciliate an existing Hellgate Token to authenticate a single payment.

Step 1 - Request Authentication Session

Request for a 60 EUR payment

curl -i -X POST \
  https://sandbox.hellgate.io/authentications/cof \
  -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": "COF_PAYMENT"
}

Step 2 - Use SDK

Use on of our SDKs to process the authentication. See the SDK documentation for more information.

Step 3 - Process Result

You'll 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": "COF_PAYMENT"
}

In case the Hellgate Token was backed by a network token, you also get the associated token authentication value (TAVV) in the response. It is encrypted using the merchant's encryption key.

Initial Recurring

This is the first payment in a row of recurring paymeents and requires a customer be present as well (API Reference). The process of running such type of authenticaiton is similar to the one described above.

The authentication is requested on /authentications/recurring and requires a slighly different set of parameters:

{
  "amount": 6000,
  "currency_code": "EUR",
  "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39",
  "recurring_exiry": 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.

info

Any further authentication will be able to authenticate at max up to the amount of the initial authentication.

Initial Installment

This is the first payment in a row of installment payments and requires a customer be present as well (API Reference). The process of running such type of authenticaiton is again very similar to the one described above.

The authentication is requested on /authentications/installment and requires a modified set of parameters:

{
  "amount": 6000,
  "currency_code": "EUR",
  "token_id": "dcfe3e92-730b-4db5-9f1c-9e10c2f62d39",
  "number_of_installments": 12,
  "recurring_exiry": 20281231,
  "recurring_frequency": 28
}

The new parameter is the number_of_installments in the plan.

info

The requestor will be able to authenticate the number of specified installments up to in total to the amount of the initial authentication.