--- updatedAt: 2026-07-02T14:11:16.000Z agentTools: projectIndex: https://suregifts-pos-api.readme.io/llms.txt --- # Find active transaction by external 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 ```bash curl -X GET \ 'https://{baseUrl}/merchant-client/v2/transactions/REF123' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' ``` 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** ```json { "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** ```json { "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. # OpenAPI definition ````json { "openapi": "3.0.4", "info": { "title": "Suregifts.Vouchers.API - merchant-client", "version": "merchant-client" }, "servers": [ { "url": "https://staging-onlinemerchants.suregifts.com", "description": "Test " }, { "url": "https://onlinemerchants.suregifts.com", "description": "Production " } ], "paths": { "/api/v2/transactions/{reference}": { "get": { "tags": [ "OnlineMerchantsV2" ], "summary": "Find active transaction by external reference", "description": "This endpoint retrieves the active (non-canceled) redemption transaction using your external reference. \nIf the transaction has been updated, this returns the NEW (current) transaction, not the original canceled one.\n\n### Request\n\n**Method:** GET \n**URL:** /merchant-client/v2/transactions/{reference} \n**Path Parameters:**\n\n- **reference** (string, required) – Your unique external reference used during redemption.\n\n**Query Parameters:** None \n**Body:** None\n\n### Responses\n\n#### 200 OK – Successful\n\n**Field Descriptions:**\n\n- **data** (object) – Active transaction details including status, amount, and timestamp.\n - **transactionId** (string) – Unique transaction ID.\n - **transactionType** (string) – Transaction type (REDEMPTION, ACTIVATION, REDEMPTION_REVERSAL).\n - **amount** (decimal) – Transaction amount.\n - **timestamp** (datetime) – Transaction timestamp.\n - **reference** (string) – Your external reference.\n - **voucherCode** (string) – Masked voucher code.\n - **serialNumber** (string) – Voucher serial number.\n - **refundStatus** (string, nullable) – Refund status: \"CANCELLED\", \"NEW\", or null for normal transactions.\n - **note** (string, nullable) – Descriptive note about transaction updates/reversals.\n- **statusCode** (string) – Status code (`\"00\"` indicates success).\n- **message** (string) – Human-readable message.\n\n#### 401 Unauthorized\n\nReturned when authentication fails.\n\n```\nUnauthorized\n```\n\n#### 404 Not Found\n\nReturned when no active transaction is found with the given external reference.\n\n```\nTransaction not found\n```\n\n### Example cURL Request\n\n```bash\ncurl -X GET \\\n 'https://{baseUrl}/merchant-client/v2/transactions/REF123' \\\n -H 'Content-Type: application/json' \\\n -H 'Accept: application/json'\n```", "parameters": [ { "name": "reference", "in": "path", "description": "Your unique external reference. Returns the active (non-canceled) redemption transaction.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnlineMerchantResult1TransactionResult_4734" } } } } }, "security": [ { "basic": [] } ] } } }, "components": { "schemas": { "OnlineMerchantResult1TransactionResult_4734": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TransactionResult462390761" }, "statusCode": { "type": "string", "description": "Request status code", "readOnly": true }, "message": { "type": "string", "description": "Human readable description of the status code", "nullable": true, "readOnly": true } }, "additionalProperties": false }, "TransactionResult462390761": { "required": [ "amount", "reference", "serialNumber", "timestamp", "transactionId", "transactionType", "voucherCode" ], "type": "object", "properties": { "voucherCode": { "minLength": 1, "type": "string", "description": "The voucher code that was utilized in this transaction (required)" }, "serialNumber": { "minLength": 1, "type": "string", "description": "The serial number of voucher that was utilized in this transaction (required)" }, "transactionId": { "minLength": 1, "type": "string", "description": "The transaction's unique number generated by Suregifts (required)" }, "transactionType": { "minLength": 1, "type": "string", "description": "Transaction type\n \n```ACTIVATION``` ```REDEMPTION``` ```REDEMPTION_REVERSAL```", "readOnly": true }, "amount": { "type": "number", "description": "Transaction amount (required)", "format": "double" }, "timestamp": { "type": "string", "description": "The time and date of the transaction (required)", "format": "date-time" }, "reference": { "minLength": 1, "type": "string", "description": "Your unique reference. The transactions (activation/redemption) were created using this reference (required)" }, "note": { "type": "string", "description": "Descriptive note explaining what happened to this transaction during an update/reversal event.\nContains a human-readable message describing:\n- For original transactions: Details about cancellation and replacement\n- For cancellation transactions: Which original transaction was reversed\n- For new transactions: Which original transaction it was created from\nNull or empty if transaction was not part of an update event.", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "basic": { "type": "http", "description": "Basic Authentication", "scheme": "basic" } } } } ````