Installment payments are ideal for businesses offering high-value products or services, enabling customers to pay in multiple parts over time through API-driven workflows—without relying on the N-Genius Online virtual terminal.
This section walks you through the full integration journey, from generating access tokens to receiving payment notifications.
This integration method involves handling sensitive cardholder data and requires PCI DSS compliance on your server environment.
Note: Installment Payments available billing intervals:
Daily, Weekly, Monthly, or Annually.
Feature Activation Required
Installment Payments are disabled by default. To enable this feature, please reach out to your Relationship Manager or contact the E-Commerce Support Team.
🧭 Integration Flow
Setting up Installment Payments: A step-by-step guide from order to automated billing.
📦 Download Postman Collection
Download the full Installment Payments Postman Collection to speed up integration and testing.
Once we have the access token, we are now able to create installment 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.ksa.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-recurring-payment.v2+json |
| Accept | application/vnd.ni-recurring-payment.v2+json |
Body:
Add the following JSON information to the form/body content of your request.
| Attribute | Description | Example |
|---|---|---|
| action | Payment processing method | 'PURCHASE', 'AUTH' |
| channel | Payment processing channel | 'MoTo' |
| type | Type of payment requested | 'INSTALLMENT' |
| frequency | Frequency/interval of payment | Various (see below) |
| emailAddress | Customer email address | [email protected] |
| amount | amount data block | N/A |
| amount.currencyCode | Order currency | 'SAR' |
| amount.value | Recurring amount | 1000 ( = 10.00 SAR) |
| installmentDetails | installmentDetails data block | N/A |
| installmentDetails.numberOfTenure | Number of Tenure | 3 ( > 1 ) |
*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. |
Installment Details:
Number of Tenure:
Specifies the total number of installment transactions.
For example, if a customer needs to be charged 10 SAR monthly for 6 months, the Number of Tenure should be set to 6.
Example request (body):
{
"action":"PURCHASE",
"type": "INSTALLMENT",
"frequency": "MONTHLY",
"emailAddress": "[email protected]",
"amount": {
"currencyCode":"SAR",
"value":1500
},
"installmentDetails": {
"numberOfTenure": 6
}
}
Example response (body):
{
"reference": "3ddf7897-3ace-402f-bdae-0297c631db84",
"amount": {
"currencyCode": "SAR",
"value": 1500
},
"action": "PURCHASE",
"installmentDetails": {
"numberOfTenure": 6,
"currentPayment": 0,
"startDate": "2025-06-20T09:21:37.993982922Z",
"endDate": "2025-06-20T14:22:37.993982922Z",
},
"type": "INSTALLMENT",
"frequency": "MONTHLY",
"paymentMethods": {
"card": [
"MADA",
"VISA",
"MASTERCARD"
]
},
"_links": {
"cnp:payment-link": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84/payment-link"
},
"payment-authorization": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/paymentAuthorization"
},
"self": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84"
},
"tenant-brand": {
"href": "http://config-service/config/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/configs/tenant-brand"
},
"payment": {
"href": "https://paypage.infradev.ksa.ngenius-payments.com/?code=237dc8e90d3cee18"
},
"merchant-brand": {
"href": "http://config-service/config/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/configs/merchant-brand"
}
},
"_embedded": {
"payment": [
{
"_id": "urn:payment:f3815f2b-2a71-4f96-848d-f33daa7f2c8e",
"_links": {
"cnp:capture": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84/payments/f3815f2b-2a71-4f96-848d-f33daa7f2c8e/captures"
},
"self": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84/payments/f3815f2b-2a71-4f96-848d-f33daa7f2c8e"
},
"payment:card": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84/payments/f3815f2b-2a71-4f96-848d-f33daa7f2c8e/card"
},
"payment:saved-card": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/63ecfe89-f7b3-4a06-9e12-d218d772020d/orders/3ddf7897-3ace-402f-bdae-0297c631db84/payments/f3815f2b-2a71-4f96-848d-f33daa7f2c8e/saved-card"
},
"curies": [
{
"name": "cnp",
"href": "http://transaction-service/docs/rels/{rel}",
"templated": true
}
]
},
"reference": "f3815f2b-2a71-4f96-848d-f33daa7f2c8e",
"state": "STARTED",
"amount": {
"currencyCode": "SAR",
"value": 1500
},
"updateDateTime": "2025-06-20T08:56:10.328184942Z",
"outletId": "63ecfe89-f7b3-4a06-9e12-d218d772020d",
"orderReference": "3ddf7897-3ace-402f-bdae-0297c631db84"
}
]
}
}
Response attributes:
| Attribute | Description | Example |
|---|---|---|
| reference | Order reference | [UUID] |
| frequency | The agreed frequency/interval of the recurring payment | 'MONTHLY', 'DAILY' |
| outletId | The reference of the outlet which accepted the payment | [UUID] |
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).