Voiding a successfully authorized payment will cancel the authorization that your customer’s issuing bank has provided as evidence of your transaction. Where supported by your customer’s issuing bank, this action will also release the funds that were previously held in readiness for a subsequent funds transfer (capture)
Partial void functionality is available in the KSA region, enabling merchants to partially void authenticated transaction amounts while retaining the ability to capture the non-voided amount. Consequently, orders remain open until the complete authenticated amount is either voided or captured.
This feature is supported by major payment networks such as MADA, VISA, and Mastercard (MC).
Key Points:
Access to conduct partial voids is restricted solely to Merchant administrators.
The ‘Void’ option must be activated within the payment channel
HTTP Request Method: PUT
Resource (URI): https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/[outlet-reference]/orders/[order-reference]/payments/[payment-reference]/cancel
Dynamic resource from order object:
response._embedded.payment[index]._links.[“cnp:cancel”].href
Headers:
| Key | Value |
|---|---|
| Authorization | Bearer [access_token] |
| Content-Type | application/vnd.ni-payment.v2+json |
| Accept | application/vnd.ni-payment.v2+json |
Body / Form Data:
| Attribute | Example value | Description |
|---|---|---|
| amount { } | N/A | Amount block |
| amount.currencyCode | SAR | Currency code (must match the currency code of the original authorization). |
| amount.value | 100 | Amount value (must not exceed the original authorization amount) |
Example request (body):
{
"amount": { "currencyCode": "SAR", "value": 100 }
}
Example response (body):
{
"_id": "urn:payment:ea55a956-5d52-42a7-9503-c5de65806dd9",
"_links": {
"self": {
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/cb8723e3-d2a4-4bc1-af70-9bbefdda13bb/payments/ea55a956-5d52-42a7-9503-c5de65806dd9"
},
"curies": [
{
"name": "cnp",
"href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/docs/rels/{rel}",
"templated": true
}
]
},
"reference": "ea55a956-5d52-42a7-9503-c5de65806dd9",
"paymentMethod": {
"expiry": "2029-04",
"cardholderName": "Jane Doe",
"name": "VISA",
"pan": "411111******1111"
},
"savedCard": {
"maskedPan": "411111******1111",
"expiry": "2029-04",
"cardholderName": "Jane Doe",
"scheme": "VISA",
"cardToken": "dG9rZW5pemVkUGFuLy92MS8vU0hPV19OT05FLy8xMTExMTExNDExMTExMTEx",
"recaptureCsc": true
},
"state": "REVERSED",
"amount": {
"currencyCode": "SAR",
"value": 7654321
},
"updateDateTime": "2025-04-23T10:50:56.341037625Z",
"outletId": "670bfc06-63d6-472b-af75-ad0207ac44f5",
"orderReference": "cb8723e3-d2a4-4bc1-af70-9bbefdda13bb",
"originIp": "196.5.8.18",
"authResponse": {
"authorizationCode": "AB0012",
"success": true,
"resultCode": "00",
"resultMessage": "Successful approval/completion or that VIP PIN verification is valid",
"mid": "10089865858",
"systemAuditTraceNumber": "043891",
"rrn": "511210043891"
},
"3ds2": {
"eci": "05",
"transStatus": "Y",
"messageVersion": "2.2.0",
"acsReferenceNumber": "00001ACS00001",
"threeDSMethodURL": "https://paypage.ksa.ngenius-payments.com/fake/3ds2/method",
"threeDSServerTransID": "6f504b78-7bf9-4afc-95f9-63ee17bdf22d",
"acsURL": "https://paypage.ksa.ngenius-payments.com/fake/3ds2/acs?challengeNotificationUrl=https%3A%2F%2FnotificationURL.com",
"acsTransID": "8ce532a9-3dd4-474a-9fc9-3dc411a6063b",
"directoryServerID": "M000000004",
"base64EncodedCReq": "eyJ0cmFuc1N0YXR1cyI6IkMiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjZmNTA0Yjc4LTdiZjktNGFmYy05NWY5LTYzZWUxN2JkZjIyZCIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4yLjAiLCJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIjoiMDEiLCJtZXNzYWdlVHlwZSI6IjAxIiwiYWNzVHJhbnNJRCI6IjhjZTUzMmE5LTNkZDQtNDc0YS05ZmM5LTNkYzQxMWE2MDYzYiJ9"
},
"mid": "10089865858"
}