Developers
HomeMerchantsDevelopers

Full or partial Refund of a Capture

You may refund all or a part of the value of a captured payment, which will return the funds previously settled to you from your customer, by identifying the appropriate capture you wish to refund, and executing the following operation against its /[capture-reference]/refund endpoint.

HTTP Request Method: POST

Resource (URI): https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/[outlet-reference]/orders/[order-reference]/payments/[payment-reference]/captures/[capture-reference]/refund

Dynamic resource from order object:

You can dynamically generate the refund URL using the self.href value from the cnp:capture object, then append /refund to it, as shown below:

response._embedded["cnp:capture"][0]._links.self.href + "/refund"

Headers:

HeaderKey
AuthorizationBearer [access_token]
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Body / Form Data:

KeyValue
amount { }N/A
amount.currencyCodeSAR
amount.valueMinor units (i.e. 100 = 1.00 SAR)

Example request (body):

{
  "amount": {
    "currencyCode": "SAR",
    "value": 100
  }
}

Example response body

{
  "_id": "urn:payment:ee0c8237-b3a6-42d3-a78a-92b6d4610136",
  "_links": {
    "self": {
      "href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/90679d17-7600-4527-91cf-e20ecf8baddd/payments/ee0c8237-b3a6-42d3-a78a-92b6d4610136"
    },
    "curies": [
      {
        "name": "cnp",
        "href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/docs/rels/{rel}",
        "templated": true
      }
    ]
  },
  "reference": "ee0c8237-b3a6-42d3-a78a-92b6d4610136",
  "paymentMethod": {
    "expiry": "2029-04",
    "cardholderName": "Bruce Wayne",
    "name": "VISA",
    "pan": "411111******1111"
  },
  "state": "REFUNDED",
  "amount": {
    "currencyCode": "SAR",
    "value": 7654321
  },
  "updateDateTime": "2025-04-24T10:31:41.782344679Z",
  "outletId": "670bfc06-63d6-472b-af75-ad0207ac44f5",
  "orderReference": "90679d17-7600-4527-91cf-e20ecf8baddd",
  "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": "048270",
    "rrn": "511307048270"
  },
  "3ds2": {
    "eci": "05",
    "transStatus": "Y",
    "messageVersion": "2.2.0",
    "acsReferenceNumber": "00001ACS00001",
    "threeDSMethodURL": "https://paypage-uat.ngenius-payments.com/fake/3ds2/method",
    "threeDSServerTransID": "ec715d59-013c-41e5-b3e2-11c8f502e39d",
    "acsURL": "https://paypage-uat.ngenius-payments.com/fake/3ds2/acs?challengeNotificationUrl=https%3A%2F%2FnotificationURL.com",
    "acsTransID": "2a6f8980-b236-46dd-8cb2-1c279b2b2180",
    "directoryServerID": "M000000004",
    "base64EncodedCReq": "eyJ0cmFuc1N0YXR1cyI6IkMiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVjNzE1ZDU5LTAxM2MtNDFlNS1iM2UyLTExYzhmNTAyZTM5ZCIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4yLjAiLCJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIjoiMDEiLCJtZXNzYWdlVHlwZSI6IjAxIiwiYWNzVHJhbnNJRCI6IjJhNmY4OTgwLWIyMzYtNDZkZC04Y2IyLTFjMjc5YjJiMjE4MCJ9"
  },
  "mid": "10089865858",
  "_embedded": {
    "cnp:capture": [
      {
        "amount": {
          "currencyCode": "SAR",
          "value": 7654321
        },
        "createdTime": "2025-04-24T07:46:57.584579280Z",
        "state": "SUCCESS"
      }
    ],
    "cnp:refund": [
      {
        "_links": {
          "self": {
            "href": "https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/90679d17-7600-4527-91cf-e20ecf8baddd/payments/ee0c8237-b3a6-42d3-a78a-92b6d4610136/refund/56515e58-1f91-4f50-91bf-2061e87767e0"
          }
        },
        "amount": {
          "currencyCode": "SAR",
          "value": 7654321
        },
        "createdTime": "2025-04-24T10:31:41.782298878Z",
        "state": "SUCCESS"
      }
    ]
  }
}

⚓

Developer Lifesaver

If you're issuing a refund against a previously settled (purchased) transaction, you can retrieve the correct POST URI for the refund request by calling the Retrieve Order Status API.

Look for the following field in the response:

response._embedded.payment[0]._links["cnp:refund"].href

This attribute contains the correct URI to initiate the refund.

📘 See Retrieve Order Status API

📘

Note: Refunds can only be initiated against payments in a PURCHASED or CAPTURED state.