Customer Initiated

Initial installment

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. Commerce utilizes the action_requirement mechanism to request any necessary interaction with the customer. The interactions are supported with SDKs. See the SDK documentation for more information.

POST

authentications

installment

Initial installment

curl --request POST \
  --url https://sandbox.hellgate.io/authentications/installment \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://sandbox.hellgate.io/authentications/installment"

payload = {
    "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"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://sandbox.hellgate.io/authentications/installment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.hellgate.io/authentications/installment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.hellgate.io/authentications/installment"

	payload := strings.NewReader("{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.hellgate.io/authentications/installment")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.hellgate.io/authentications/installment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Body

application/json

amount

integer

required

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.

Required range: x >= 0

currency_code

string

required

The three letter currency code. See: ISO-4217

number_of_installments

integer

required

Indicates the maximum number of authorisations permitted for installment payments.

recurring_expiry

string

required

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

recurring_frequency

integer

required

Indicates the minimum number of days between authorisations.

source

object

required

The payment credentials for this authentication request.

Type	Description
token	An already existing Commerce token can be used as source for the authentication.

Show child attributes

challenge_preference

enum<string>

default:CHALLENGE

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Available options:

CHALLENGE,

NO_PREFERENCE,

NO_CHALLENGE

purchase_date

string

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

merchant_id

string<uuid>

The ID of the merchant for whom the authentication is requested

cardholder_information

object

Show child attributes

Response

Authentication created

string<uuid>

required

The ID of the authentication

amount

integer

required

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.

Required range: x >= 0

created_at

string<datetime>

required

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

currency_code

string

required

The three letter currency code. See: ISO-4217

status

enum<string>

required

Available options:

PROCESSING,

COMPLETED,

FAILED

source

object

required

The payment credentials for this authentication request.

Type	Description
token	An already existing Commerce token can be used as source for the authentication.

Show child attributes

use_case

enum<string>

required

Available options:

ONE_OFF,

INITIAL_RECURRING,

INITIAL_INSTALLMENT,

SUBSEQUENT_RECURRING,

SUBSEQUENT_INSTALLMENT

action_requirement

object

Show child attributes

authentication_result

object

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

Show child attributes

challenge_preference

enum<string>

default:CHALLENGE

The preference with respect to an eventual challenge.

There is no guarantee that the preference can be fulfilled.

Available options:

CHALLENGE,

NO_PREFERENCE,

NO_CHALLENGE

recurring_expiry

string

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

recurring_frequency

integer

Indicates the minimum number of days between authentications.

failure_details

object[]

The reasons why an authentication failed during processing in Commerce.

Show child attributes

finished_at

string<datetime>

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

original_authentication

string<uuid>

The ID of the original authentication in case of subsequent authentications

merchant_id

string<uuid>

The ID of the merchant for whom the authentication is requested

number_of_installments

integer

Indicates the maximum number of authorisations permitted for installment payments.

purchase_date

string

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

Subsequent recurringAuthenticate 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.

⌘I

Initial installment

curl --request POST \
  --url https://sandbox.hellgate.io/authentications/installment \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://sandbox.hellgate.io/authentications/installment"

payload = {
    "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"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://sandbox.hellgate.io/authentications/installment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.hellgate.io/authentications/installment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.hellgate.io/authentications/installment"

	payload := strings.NewReader("{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.hellgate.io/authentications/installment")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.hellgate.io/authentications/installment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1000,\n  \"currency_code\": \"EUR\",\n  \"recurring_expiry\": \"20231231\",\n  \"recurring_frequency\": 28,\n  \"number_of_installments\": 12,\n  \"source\": {\n    \"type\": \"token\",\n    \"token_id\": \"71820e49-6822-4df1-8db5-d245456172b6\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

Getting Started

Payments

Authentications

Customer Data

Tokens

Configuration

Automation

Initial installment

Authorizations

Body

Response