Find the Transaction

Search by the approval code from the customer's receipt to find the original payment and its transaction ID. You refund against that ID in the next step.

Endpoint

GET /unified-reporting/merchants/{merchantId}/transactions

Headers

Header	Required	Value
`Authorization`	Required	`Bearer <access_token>`
`Accept`	Required	`application/vnd.ni.unified-reporting.v1+json`

Parameters

Parameter	In	Required	Description
`merchantId`	Path	Required	Your merchant reference, a UUID from the N-Genius Online portal. Not the 12-character MID.
`searchField`	Query	Required	`AUTH_CODE`, to search by approval code
`searchValue`	Query	Required	The approval code from the receipt. URL-encode it if it contains special characters.
`startDate`	Query	Required	First day to search, `YYYY-MM-DD`
`endDate`	Query	Required	Last day to search, `YYYY-MM-DD`. Must be on or after `startDate`, and no more than 31 days after it.

Set both dates to the day of the payment. A narrow range returns fewer duplicate matches.

Sample request

curl --request GET \
  'https://api-gateway.sandbox.ngenius-payments.com/unified-reporting/merchants/<merchant_id>/transactions?searchField=AUTH_CODE&searchValue=<approval_code>&startDate=2026-04-09&endDate=2026-04-09' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/vnd.ni.unified-reporting.v1+json'

Successful response

{
  "items": [
    {
      "id": "757d7d02-1905-467f-8b23-fb82d1bd6573",
      "channel": "POS",
      "nodeRef": "32fbde01-c504-4e7b-a724-c61d571bdf10",
      "timestamp": "2026-04-09T08:11:00Z",
      "type": "PURCHASE",
      "status": "APPROVED",
      "amount": { "currencyCode": "AED", "value": 3500 },
      "payment": {
        "paymentMethod": "MASTERCARD",
        "card": {
          "maskedPan": "xxxxxx******xxxx",
          "entryMethod": "CONTACTLESS_INTEGRATED_CIRCUIT_CARD",
          "expiryDate": 2607,
          "cardType": "UNKNOWN"
        }
      },
      "identifiers": {
        "authCode": "xxxxxx",
        "rrn": "0000000000xx",
        "merchantId": "00x0000000xx",
        "terminalId": "xxxxxxxx",
        "paymentProvider": { "transactionId": "XXXXXXXXX" }
      },
      "settlement": {
        "id": "XXXXXXXXXXXXXXXX",
        "date": "2026-04-09",
        "status": "SETTLED",
        "netAmount": { "currencyCode": "AED", "value": 3279 },
        "commissionAmount": { "currencyCode": "AED", "value": -210 }
      }
    }
  ],
  "total": 1,
  "cursor": "CPTfFxoJKSBmS3GdAQAAGhZCFAgEEhAB..."
}

What to use from the response

Field	Use
`items[].id`	The transaction ID. Pass it to Refund the transaction.
`items[].type`	Must be `PURCHASE`, `PRE_AUTHORISATION_COMPLETION`, `MOTO` or `CASH_ADVANCE`
`items[].status`	Must be `APPROVED`
`items[].settlement`	Present once the transaction has settled. Only settled transactions can be refunded, so a transaction without this block cannot be refunded yet.
`items[].amount`	Original amount, in minor units: 3500 is AED 35.00
`items[].identifiers`	Merchant ID, terminal ID, RRN and approval code, for telling matches apart

More than one match

An approval code is not unique. If total is more than 1, pick the right transaction on your own server by comparing the merchant ID, terminal ID, the last four digits of maskedPan, or the RRN.

No match

A search that finds nothing still returns HTTP 200, with an empty list:

{ "items": [], "total": 0 }

Check the approval code against the receipt, and widen the date range, keeping it within 31 days.

Errors

HTTP	When	What to do
401	The access token is missing, wrong or expired	Request a new token and retry
422	`endDate` is before `startDate`, or more than 31 days after it	Correct the date range

See Errors and troubleshooting for the full list.