Recurring Transactions

What are Recurring Transactions?

Recurring transactions are automatic payments that take effect on a certain date after a subscription. Recurring transactions operate on a predetermined schedule established by a consumer.

The recurring transactions could be initiated by Customers (Customer initiated transaction – CIT) or initiated by a merchant (Merchant initiated transaction – MIT).

For the subsequest recurring transactions, the cardholder or merchant will not have to provide card details, CVV2/CVC2/CAV2 (Secure code), or pass 3-D Secure again.

First Recurring Transaction

To establish the first recurring transactions, the following parameters have to be included in the request body:

“recurring”: true
“merchantInitiated”: false

Parameters

Parameter

Type

Description

amount

number

Transaction Amount

currency

string

ISO 3 Currency Code

action

string

Enum: “Authorize”, “Purchase”

recurring

boolean

Flags the transaction as a recurring transaction. The default value is false.

merchant

Initiated boolean

Flags the transaction as a merchant-initiated transaction (MIT). The default value is false that refers to cardholder-initiated transactions (CITs).

recurringFrequencyInDays

string

Indicates the minimum number of days between authorisations. The field is limited to maximum 4 characters. Default value: 30 days

recurringExpiryInDays

string

Indicates the days till the recurring expires. Default value: 30 days

customer

object

Link to customer object

source

object

Link to source object

statementDescriptor

string <= 21

An optional billing descriptor displayed on the account owner’s statement

description

string <= 150

Transaction description

reference

string <= 20

Merchant reference

ipAddress

string <= 45 characters

Consumer’s IP Address

successUrl

string <= 255 characters

For redirect payment methods, this overrides the default success redirect URL configured on your account

cancelUrl

string <= 255 characters

For redirect payment methods, this overrides the default cancel redirect URL configured on your account

failureUrl

string <= 255 characters

For redirect payment methods, this overrides the default failure redirect URL configured on your account

JSON Request object

POST https://api.quaife.net/v1/transactions/

{
“amount”:10,
“currency”:”EUR”,
“action”:”Authorize”,
“recurring”: true,
“recurringFrequencyInDays”:”1″,
“recurringExpiryInDays”:”200″,
“merchantInitiated”: false,
“customer”:{
“firstName”: “Max”,
“lastName”: “Muster”,
“email”: “max@example.com”,
“phone”: “+234323423”,
“accountReference”:”acc0002″,
“category”: “gaming”,
“address”: {
“streetAddress”:”3 Malpas Road”,
“city”: “Great Sutton”,
“postcode”:”CH65 7BQ”,
“country”:”GB”
}
},
“source”:{
“paymentMethod”: “VISA”,
“holder”: “Max Muster”,
“cardNumber”:”5101080000000009″,
“expiryMonth”: 12,
“expiryYear”: 20,
“cvc”: “123”,
“billingAddress”: {
“streetAddress”:”3 Malpas Road”,
“city”: “Great Sutton”,
“postcode”:”CH65 7BQ”,
“country”:”GB”
}
},
“statementDescriptor”:”Purchase my-shop.com”,
“Description”:”T-Shirt XXL”,
“Reference”:”ORD24234″,
“ipAddress”:”117.174.147.27″,
“successUrl”:”https://example.com/home/success”,
“cancelUrl”:”https://example.com/home”,
“failureUrl”:”https://example.com/home/cancel”
}

JSON Response object

{
“id”: “trn_lsbt1or4xy”,
“status”: “Pending”,
“amount”: 100.0,
“currency”: “EUR”,
“recurring”: true,
“merchantInitiated”: false,
“source”: {
“id”: “src_u8l7s06px5”,
“paymentMethod”: “VISA”,
“cardNumber”: “510108xxxxxx0009”,
“holder”: “Max Muster”
},
“customer”: {
“id”: “cus_wlydwqmn59”,
“firstName”: “Max”,
“lastName”: “Muster”,
“email”: “max@example.com”
},
“created”: “2020-12-18T15:24:13.8524886Z”,
“links”: [
{
“href”: “https://payage.net/3d-transactions/allnl1ic9krs2smp6ywmcqwlard9o77dk107zpno”,
“rel”: “redirect”,
“method”: “GET”
}
]
}

Flow

Subsequent Recurring Transactions

After creating the first recurring transaction, subsequent transactions must have the following parameters in the request body:

“recurring”: true
“merchantInitiated”: true

The transaction ID generated from the first recurring transaction should be used in the subsequent recurring transaction request object. Kindly note Authorised transactions will first need to be “Captured”. The “Captured” transaction (trn_***) must be included in the below request.

Parameters

POST https://api.quaife.net/v1/transactions/

Parameter

Type

Description

amount

number

Transaction Amount

currency

string

ISO 3 Currency Code

action

string

Enum: “Authorize”, “Purchase”

recurring

boolean

Flags the transaction as a recurring transaction. The default value is false

merchantInitiated

boolean

Flags the transaction as a merchant-initiated transaction (MIT). The default value is false that refers to cardholder-initiated transactions (CITs)

firstRecurringTransactionId

string

Transaction identifier from the recurring series. Response of the first recurring transaction

statementDescriptor

string <= 21

An optional billing descriptor displayed on the account owner’s statement

description

string <= 150

Transaction description

reference

string <= 20

Merchant reference

ipAddress

string <= 45

characters Consumer’s IP Address

JSON Response object

{
“amount”:10,
“currency”:”EUR”,
“action”:”Authorize”,
“recurring”: true,
“merchantInitiated”: true,
“firstRecurringTransactionId”: “trn_lsbt1or4xy”,
“statementDescriptor”:”Purchase my-shop.com”,
“Description”:”T-Shirt XXL”,
“Reference”:”ORD24234″,
“ipAddress”:”117.174.147.27″
}

JSON Response Object

{
“id”: “trn_lsbt1or4ab”,
“status”: “Pending”,
“amount”: 100.0,
“currency”: “EUR”,
“recurring”: true,
“merchantInitiated”: false,
“firstRecurringTransactionId”: “trn_lsbt1or4xy”,
“source”: {
“id”: “src_u8l7s06px5”,
“paymentMethod”: “VISA”,
“cardNumber”: “510108xxxxxx0009”,
“holder”: “Max Muster”
},
“customer”: {
“id”: “cus_wlydwqmn59”,
“firstName”: “Max”,
“lastName”: “Muster”,
“email”: “max@example.com”
},
“created”: “2020-12-18T15:24:13.8524886Z”
}