Recurring Transaction

Recurring payments are commonly used to create new transactions based on already stored cardholder information from previous Authentication operations.

API Endpoint

Request URL:      {{CHECKOUT_HOST}}/api/v1/payment/reсurring
Request Method:   POST
Request Body:     JSON

{{CHECKOUT_HOST}}

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
merchant_key	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
recurring_init_trans_id	String	Required	Transaction ID of the primary transaction in the Payment Platform Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
recurring_token	String	Required	Recurring token Example: 9a2f-0242c0a87002
schedule_id	String	Optional	Schedule ID for recurring payments
hash	String	Required	Special signature to validate your request to Payment Platform. For details, click here
order	Object
number	String	Required Not blank max: 255 [a-zA-Z0-9-]	Order ID Example: order-1234
amount	Float	Required Not blank Greater then 0 0-9 max: 255	Product price. Format: XX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: xx.xxx (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND. Example: 0.19
description	String	Required min: 2 max: 1024 [a-zA-Z0-9!"#$%&'()*+,./:;&@]	Product name Example: Very important gift - # 9

Response Parameters

Parameter	Type	Mandatory, Limitations	Description
merchant_key	String	Required	Transaction status Example: PREPARE, SETTLED, PENDING, 3DS, REDIRECT, DECLINE, REFUND, REVERSAL, CHARGEBACK
reason	String	Optional	Decline reason translation for unsuccessful payment. It displays only if the transaction is unsuccessful Example: The operation was rejected. Please contact the site support
payment_id	String	Required Up to 255 characters	Transaction ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
date	String	Required Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
schedule_id	String	Optional	Schedule ID for recurring payments
order	Object
number	String	Required max: 255	Order ID Example: order-1234
amount	String	Required Format: XX.XX	Product price (currency will be defined by the first payment) Example: 0.19
currency	String	Required 3 characters	Currency Example: QAR
description	String	Required max: 1024	Product name Example: Very important gift - # 9

Examples

Request

Recurring (settled)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/reсurring' \
--data-raw \
'{
   "merchant_key": "xxxxx-xxxxx-xxxxx",
   "order":{
      "number": "order-1234",
      "amount": "0.19",
      "description": "very important gift"
},
    "customer": {
        "name": "John Doe",
        "email": "success@gmail.com"
    },     
       "recurring_init_trans_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002", 
       "recurring_token": "9a2f-0242c0a87002",
       "schedule_id": "57fddecf-17b9-4d38-9320-a670f0c29ec0", 
       "hash": "{{session_hash}}"
}'

Recurring (declined)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/reсurring' \
--data-raw \
'{ 
    "payment_id": "1f34f446-fc45-11ec-a50f-0242ac120004",
    "date": "2022-07-05 09:30:34",
    "status": "decline",
    "reason": "Declined by processing.",
    "order": {
        "number": "order-1234",
        "amount": "3.01",
        "currency": "QAR",
        "description": "bloodline"
    },
    "customer": {
        "name": "John Doe",
        "email": "success@gmail.com"
    }
}'

Response

Status Settled

{
  "status": "settled",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "date": "2020-08-05 07:41:10",
  "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "QAR",
    "description": "very important gift"
  }
}

Status Declined

{
  "status": "declined",
  "reason": "declined by processing",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "date": "2020-08-05 07:41:10",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "QAR",
    "description": "very important gift"
  }
}