Developers
HomeMerchantsDevelopers

Refund 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.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.currencyCodeAED, GBP, USD, ZAR
amount.valueMinor units (i.e. 100 = 1.00 AED)

Example request (body):

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

Example response body

{
    "_id": "urn:payment:ee0c8237-b3a6-42d3-a78a-92b6d4610136",
    "_links": {
        "self": {
            "href": "https://api-gateway.sandbox.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.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": "AED",
        "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": "AED",
                    "value": 7654321
                },
                "createdTime": "2025-04-24T07:46:57.584579280Z",
                "state": "SUCCESS"
            }
        ],
        "cnp:refund": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-gateway.sandbox.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": "AED",
                    "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.