Create a recurring payment

Now that an access token has been provided, we are now able to create recurring payments for the N-Genius Online gateway to schedule and manage.

Once the initial payment has been made successfully, the internal scheduler will automatically keep track of your payments, their frequency/interval, and request a new payment from your customer's card whenever a payment is due.

HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/recurring-payment/outlets/[your-outlet-reference]/orders

Headers:

Add these headers to your request (note that you should replace 'access_token' with the access token value we received from the Request an access token step).

Header	Value
Authorization	Bearer access_token
Content-Type	application/vnd.ni-payment.v2+json
Accept	application/vnd.ni-payment.v2+json

Body:

Add the following JSON information to the form/body content of your request.

Attribute	Description	Example
order	order data block	N/A
order.action	Payment processing method	'PURCHASE'
order.channel	Payment processing channel	'MoTo'
order.type	Type of payment requested	'RECURRING'
order.frequency	Frequency/interval of payment	Various (see below)
order.emailAddress	Customer email address	[email protected]
order.amount	order.amount data block	N/A
order.amount.currencyCode	Order currency	'AED', 'USD', etc.
order.amount.value	Recurring amount	1000 ( = 10.00 AED)
payment	payment data block	N/A
payment.pan	PAN of card (16-19 digits)	4111****1111
payment.expiry	Card expiry date	2025-04
payment.cvv	Card security code	123
payment.cardholderName	Card-holder full name	Test Customer

*Available intervals (frequencies):

Interval / frequency	Description
WEEKLY	A payment for the required amount will be attempted immediately, then every 7 days thereafter.
MONTHLY	A payment for the required amount will be attempted immediately, then every month on the same day of the month. Note that, if the date of presentment (i.e. the first transaction is between 29th-31st of any given month), subsequent payments will be taken on the 28th of each month, in order to cater for months with fewer than 30 days.
YEARLY	A payment for the required amount will be attempted immediately, then every year on the same date for each subsequent year.

Example request (body):

{
      "order": {
          "action":"PURCHASE",
          "channel": "MoTo",
          "type": "RECURRING",
          "frequency": "MONTHLY",
          "emailAddress": "[email protected]",
          "amount": {
              "currencyCode":"AED",
              "value":150 
          }
      },
      "payment":{
          "pan":"4012001037141112",
          "expiry":"2025-04",
          "cvv":"123",
          "cardholderName":"Test Customer"
      }
}

Example response (body):

{
    "state": "ACTIVE",
    "reference": "5787d6d7-765f-4716-b19f-0b6482aa802d",
    "frequency": "MONTHLY",
    "orderReference": "5787d6d7-765f-4716-b19f-0b6482aa802d",
    "outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
    "startTime": "2019-05-26T04:59:11Z",
    "nextPaymentOn": "2019-06-23T04:59:11Z"
}

Response attributes:

Attribute	Description	Example
state	Indicates whether the recurring payment is active or otherwise	'ACTIVE', 'FAILED'
reference	Reference of the container order for the recurring payment	[UUID]
frequency	The agreed frequency/interval of the recurring payment	'MONTHLY', 'DAILY'
orderReference	Order reference	[UUID]
outletId	The reference of the outlet which accepted the payment	[UUID]
startTime	Date/time of first payment	2019-05-26T04:59:11Z (UTC)
nextPaymentOn	Date/time of next payment	2019-06-23T04:59:11Z (UTC)

Note: if the 'state' attribute is returned 'ACTIVE', then you may consider the first payment (and the inclusion of your recurring payment in the N-Genius Online scheduler), successful.

However, should you wish to interrogate the order further, you may use the 'orderReference' attribute to query the order in more detail (see Retrieve order status for more information on how to do this).

🚧
Changing a recurring payment
It is not currently possible to amend or change an active recurring payment. Should you wish to amend the payment frequency, amount, or the card information associated with the order, you must first cancel the existing recurring payment, then create a new one (with the new parameters) to replace it.

Headers:

Body:

Example request (body):

Example response (body):

Response attributes:

🚧Changing a recurring payment

🚧
Changing a recurring payment