Verify Transaction Status

This endpoint allows merchants to verify the status of a transaction using the unique transaction reference.

Endpoint:

GET /transaction/verify/{transactionReference}

Headers:

Key	Value	Required	Description
Authorization	`{PRIVATE_KEY}`	Yes	The merchant’s private key.
Content-Type	`application/json`	Yes	Specifies the media type of the resource.

Path Parameters:

Parameter	Type	Required	Description
transactionReference	string	Yes	The unique reference identifier of the transaction.

Request:

There is no additional request body, as this endpoint primarily uses the path parameter and headers.

Response:

A JSON response containing details of the transaction, including its current status.

Fields in the transaction response:

Field	Type	Description
transactionReference	string	A unique identifier assigned to the transaction.
merchantRef	string	The reference provided by the merchant during the transaction.
status	string	The current status of the transaction. Refer to Transaction Status table.
statusCode	integer	The numerical code representing the transaction status. Refer to Transaction Status table.
grossAmount	decimal	The total transaction amount, including fees (e.g., 100.00).
currencyCode	string	The currency used in the transaction (e.g., "USD", "NGN").
date	string	The date and time the transaction was initiated, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
customerId	string	The unique identifier of the customer, which may include name and email.

Response (Success):

{
    "status": 200,
    "message": "Request successfully processed",
    "data": {
        "merchant": "Merchant 1",
        "transactionReference": "GjO2EBd_k1pu4mHmluXn",
        "merchantRef": "ecc0c53f-5130-4717-8ef1-1ac1ef02214c",
        "grossAmount": 50.75,
        "requestedAmount": 50.00,
        "transactionFee": 0.75,
        "settlementAmount": 49.25,
        "customerId": "[email protected]",
        "currencyCode": "NGN",
        "callbackUrl": "https://merchanturl.com",
        "authorizationType": "OPEN",
        "paymentRequestor": "Merchant Limited",
        "transactionDate": "2025-03-11T14:43:50.172275",
        "status": 2
    },
    "errors": []
}

Error Responses:

Status Code	Message	Description
401	Unauthorized	Invalid merchant private key.
403	Forbidden	IP address not whitelisted.
404	Not Found	Transaction reference not found.

Example Error Responses:

HTTP 401: Unauthorized

{
  "status": "error",
  "message": "Unauthorized request. Please provide a valid merchant private key."
}

HTTP 403: Forbidden

{
  "status": "error",
  "message": "Access denied. Your IP address is not whitelisted."
}

HTTP 404: Not Found

{
  "status": "error",
  "message": "Transaction not found for reference: TRX123456789."
}

Note:

Private Key Security: Ensure the private key is handled securely on your backend. Do not expose it on the client side (e.g., browser or mobile app).
IP Whitelisting: The merchant's IP address must be whitelisted for the private key. Contact support to configure this if needed.
Transaction Status Mapping: Refer to the Transaction Status table for all possible statuses.