Find active transaction by external reference

get

https://staging-onlinemerchants.suregifts.com/api/v2/transactions/{reference}

This endpoint retrieves the active (non-canceled) redemption transaction using your external reference.
If the transaction has been updated, this returns the NEW (current) transaction, not the original canceled one.

Request

Method: GET
URL: /merchant-client/v2/transactions/{reference}
Path Parameters:

reference (string, required) – Your unique external reference used during redemption.

Query Parameters: None
Body: None

Responses

200 OK – Successful

Field Descriptions:

data (object) – Active transaction details including status, amount, and timestamp.
- transactionId (string) – Unique transaction ID.
- transactionType (string) – Transaction type (REDEMPTION, ACTIVATION, REDEMPTION_REVERSAL).
- amount (decimal) – Transaction amount.
- timestamp (datetime) – Transaction timestamp.
- reference (string) – Your external reference.
- voucherCode (string) – Masked voucher code.
- serialNumber (string) – Voucher serial number.
- refundStatus (string, nullable) – Refund status: "CANCELLED", "NEW", or null for normal transactions.
- note (string, nullable) – Descriptive note about transaction updates/reversals.
statusCode (string) – Status code ("00" indicates success).
message (string) – Human-readable message.

401 Unauthorized

Returned when authentication fails.

Unauthorized

404 Not Found

Returned when no active transaction is found with the given external reference.

Transaction not found

Example cURL Request

curl -X GET \
  'https://{baseUrl}/merchant-client/v2/transactions/REF123' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Use this endpoint to retrieve the full details of a single transaction using the exact reference you supplied when you initiated the activation or redemption. This is the fastest way to reconcile outcomes, power receipts, or re-display a transaction to a user.

Endpoint

GET /api/v2/transactions/{reference}

Where {reference} is your unique, client-generated idempotency key.

Request

Provide the reference as a path parameter.
No request body is required.

Example

GET /api/v2/transactions/ACT-2025-0001

Response

If the endpoint is reached successfully you will receive HTTP 200. Inspect the JSON body for business outcome:

data — The transaction details for the supplied reference, including:
- voucherCode — Masked voucher code used.
- serialNumber — Voucher serial number.
- transactionId — SureGifts-generated unique transaction ID.
- transactionType — ACTIVATION or REDEMPTION.
- amount — Transaction amount.
- timestamp — When the transaction occurred (ISO 8601).
- reference — Echo of the reference you requested.
statusCode — Business status code (e.g., 00 for success, 99 if no transaction found).
message — Human‑readable description aligned with statusCode.

Example Successful Response

{
  "data": {
    "voucherCode": "112*** ***862",
    "serialNumber": "300002137",
    "transactionId": "96",
    "transactionType": "ACTIVATION",
    "amount": 5000,
    "timestamp": "2025-08-15T17:05:16.033Z",
    "reference": "ACT-2025-0001"
  },
  "statusCode": "00",
  "message": "Successful"
}

Example Not Found

{
  "data": null,
  "statusCode": "99",
  "message": "Transaction Not found"
}

Developer Notes

Use this endpoint to implement idempotent reads after uncertain network conditions.
Treat 99 (not found) as a hard failure for that reference—verify you are querying the exact string you submitted.
For auditing, store both the provider transactionId and your reference in your system.
Mask voucher codes in logs and user interfaces.

Response

Request

Response

Developer Notes

200OK