Skip to main content
POST
/
payments
/
recurring
curl --request POST \
  --url https://sandbox.hellgate.io/payments/recurring \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": 1000,
  "currency_code": "EUR",
  "reference": "Order #12345",
  "recurring_expiry": "20231010",
  "recurring_frequency": 28,
  "source": {
    "type": "checkout"
  }
}
'
{
  "id": "54ba1fdb-7e4e-402b-aebb-66f9d5345cf8",
  "amount": {
    "requested": 1000
  },
  "action_requirement": {
    "type": "use_sdk",
    "session_id": "d5b8e449-13da-4594-bf00-643146fb35d1"
  },
  "created_at": "2023-10-10T00:00:00Z",
  "currency_code": "EUR",
  "reference": "Order #12345",
  "recurring_expiry": "20231010",
  "recurring_frequency": 28,
  "status": "processing",
  "use_case": "RECURRING"
}

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

​
reference
string
required

A description of the payment for later reference

Maximum string length: 80
​
recurring_expiry
string<yyyyMMdd>
required

The date when the recurring should expiry.

​
recurring_frequency
integer
required

Indicates the minimum number of days between authorisations.

​
additional_information
object
​
source
object

The source for this initial payment.

TypeDescription
checkoutDuring the checkout an action requirement will be available, to determine the actual payment credentials from the shopper. The SDKs can be used to handle the session and safely process the payment data.
tokenAn already existing Commerce token can be used as source for the payment.
credentialAlready stored credentials are used as source for the payment.
​
splits
object[]

An optional array of split instructions.

Data in this array is only processed on a Commerce account in the platform operating model. If you are in doubt, please reach out to your account representative.

In order to have a valid split instruction, the total amount of the payment needs to be the sum of all splits.

TypeDescription
sellerSending the given amount to the seller referenced by the merchant_id in the payload. The seller needs to be onboarded to the account and linked to the processor in order to receive funds from a payment split.
commissionAn already existing Commerce token can be used as source for the payment.
Minimum array length: 1
​
metadata
object

Metadata consisting of entries, each of which each includes a key and an associated value:

  • Maximum 20 key-value pairs.
  • Maximum 20 characters per key.
  • Maximum 80 characters per value.
Example:
{
  "my_key_one": "my_value_one",
  "my_key_two": "my_value_two"
}

Response

Success response

​
id
string<uuid>
required

The ID of the payment on Commerce

​
amount
object
required
​
created_at
string<date-time>
required

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

​
currency_code
string
required

The three letter currency code. See: ISO-4217

​
reference
string
required

A description of the payment for later reference

Maximum string length: 80
​
status
enum<string>
required
Available options:
open,
processing,
failed,
authorized,
capturing,
captured,
settling,
settled,
voiding,
voided
​
use_case
enum<string>
required

Definition of the payment use-case for processing

Available options:
ONE_OFF,
UNSCHEDULED,
SUBSEQUENT_UNSCHEDULED,
RECURRING,
SUBSEQUENT_RECURRING
​
action_requirement
object
​
additional_information
object
​
authentication_preference
enum<string>
default:NO_3RI

The preference for the authentication method to be used for the payment.

PreferenceDescription
NO_3RIDon't perform 3RI authentication for this payment (Default).
TRY_3RITry to perform 3RI authentication for this payment. If it fails the payment will still be sent for authorization.
REQUIRE_3RIRequire 3RI authentication for this payment. If it fails the payment will not be sent for authorization.
Available options:
NO_3RI,
TRY_3RI,
REQUIRE_3RI
​
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).

​
credential_id
string<uuid>

The ID of the credential associated with the payment.

​
failure_details
object[]

The reasons why a payment failed during processing in Commerce.

This can be due to processing errors on the side of the processor, as well as errors in the processing of the underlying flow.

In case the failure is due to a processing problem, the transaction history of the payment can give more information on the exact failure details.

​
flow_matrix_rule
string

The rule in the flow matrix, which was chosen to process the payment.

​
initial_payment_id
string<uuid>

The ID of the initial payment.

Only present for subsequent merchant-initiated payments.

​
processing_annotations
object

This is an optional attribute holding results from eventual pre-processing of the request.

​
recurring_expiry
string<yyyyMMdd>

The date when the recurring should expiry.

Only present for recurring payments.

​
recurring_frequency
integer

Indicates the minimum number of days between authorisations.

Only present for recurring payments.

​
source
object

The source that was used for the payment.

TypeDescription
cardThe payment method card was used as source
​
splits
object[]

An array of split instructions.

Data in this array is only processed on a Commerce account in the platform operating model. If you are in doubt, please reach out to your account representative.

TypeDescription
sellerSending the given amount to the seller referenced by the merchant_id in the payload. The seller needs to be onboarded to the account and linked to the processor in order to receive funds from a payment split.
commissionAn already existing Commerce token can be used as source for the payment.
Minimum array length: 1
​
metadata
object

Metadata consisting of entries, each of which each includes a key and an associated value:

  • Maximum 20 key-value pairs.
  • Maximum 20 characters per key.
  • Maximum 80 characters per value.
Example:
{
  "my_key_one": "my_value_one",
  "my_key_two": "my_value_two"
}