TransactionsGet Transaction by Reference

Get Transaction by Reference

Retrieve transaction details using a unique reference identifier. This endpoint allows you to verify and fetch the status of any transaction using its reference code.

Endpoint

GET https://backendapi.sayswitchgroup.com/api/v1/transaction/verify/{reference}

Path Parameter

ParameterTypeRequiredDescription
referencestringYesThe unique transaction reference code

Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_SECRET_KEY"
}

Example Request

curl --location --request GET 'https://backendapi.sayswitchgroup.com/api/v1/transaction/verify/TEST_TXN_REF_001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'

Note: This is a GET request, so no request body is required. The reference is passed in the URL path.

Response

Success Response

{
    "success": true,
    "message": "Transaction retrieved successfully",
    "data": {
        "id": 12345,
        "domain": "test",
        "status": "success",
        "reference": "TEST_TXN_REF_001",
        "amount": "1012",
        "gateway_response": "Transaction successful",
        "paid_at": "2025-10-01T14:30:25.000000Z",
        "created_at": "2025-10-01T14:30:15.000000Z",
        "channel": "card",
        "currency": "NGN",
        "ip_address": "192.168.1.100",
        "fees": "12",
        "requested_amount": "1000"
    },
    "customer": {
        "id": 456,
        "customer_code": "CUS_test123456789",
        "first_name": "John",
        "last_name": "Doe",
        "email": "test@example.com",
        "phone": "08012345678",
        "metadata": "{}"
    },
    "log": {
        "time_spent": 15000,
        "attempts": 1,
        "authentication": "successful",
        "errors": 0,
        "success": true,
        "channel": "card",
        "history": [
            {
                "id": 1001,
                "type": "TRANSACTION_INITIATED",
                "message": "Transaction started",
                "time": "2025-10-01T14:30:15.000000Z",
                "reference": "TEST_TXN_REF_001",
                "channel": "card"
            },
            {
                "id": 1002,
                "type": "PAYMENT_COMPLETED",
                "message": "Payment successful",
                "time": "2025-10-01T14:30:25.000000Z",
                "reference": "TEST_TXN_REF_001",
                "channel": "card"
            }
        ]
    },
    "plan": null,
    "authorization": {
        "authorization_code": "AUTH_test_12345",
        "bin": "411111",
        "last4": "1111",
        "exp_month": "12",
        "exp_year": "28",
        "card_type": "visa",
        "bank": "Test Bank",
        "country_code": "NG",
        "brand": "visa",
        "reusable": true
    }
}

Error Response

{
    "success": false,
    "message": "Transaction not found",
    "error": "No transaction found with reference: INVALID_REF_001"
}

Response Fields

Main Transaction Data

FieldTypeDescription
successbooleanIndicates if the request was successful
messagestringDescriptive message about the request status
dataobjectMain transaction details
data.idintegerUnique transaction identifier
data.domainstringEnvironment (test/live)
data.statusstringTransaction status
data.referencestringUnique transaction reference
data.amountstringFinal amount charged (including fees)
data.requested_amountstringOriginal requested amount
data.feesstringTransaction fees
data.currencystringTransaction currency
data.channelstringPayment channel used
data.gateway_responsestringResponse from payment gateway
data.paid_atstringPayment completion timestamp
data.created_atstringTransaction creation timestamp
data.ip_addressstringCustomer’s IP address

Customer Information

FieldTypeDescription
customer.idintegerCustomer’s unique identifier
customer.customer_codestringCustomer’s unique code
customer.first_namestringCustomer’s first name
customer.last_namestringCustomer’s last name
customer.emailstringCustomer’s email address
customer.phonestringCustomer’s phone number
customer.metadatastringAdditional customer data

Transaction Log

FieldTypeDescription
log.time_spentintegerProcessing time in milliseconds
log.attemptsintegerNumber of processing attempts
log.authenticationstringAuthentication status
log.errorsintegerNumber of errors encountered
log.successbooleanOverall success status
log.channelstringPayment channel
log.historyarrayDetailed transaction events

Authorization Details (Card Payments)

FieldTypeDescription
authorization.authorization_codestringAuthorization code for future charges
authorization.binstringBank Identification Number
authorization.last4stringLast 4 digits of card
authorization.exp_monthstringCard expiry month
authorization.exp_yearstringCard expiry year
authorization.card_typestringType of card (visa, mastercard, etc.)
authorization.bankstringIssuing bank name
authorization.country_codestringCard issuing country
authorization.reusablebooleanWhether authorization can be reused

Transaction Status Values

StatusDescription
successTransaction completed successfully
pendingTransaction is still processing
failedTransaction failed or was declined
cancelledTransaction was cancelled

Error Handling

Common Error Responses

Status CodeDescriptionResponse
404Transaction not found{"success": false, "message": "Transaction not found"}
401Unauthorized{"success": false, "message": "Invalid API key"}
400Bad request{"success": false, "message": "Invalid reference format"}
500Server error{"success": false, "message": "Internal server error"}

Best Practices

  1. Always check the success field before processing response data
  2. Handle different transaction statuses appropriately in your application
  3. Implement retry logic for failed requests with exponential backoff
  4. Store transaction references securely for future verification
  5. Validate response data before using it in your application
Get Transaction DetailsTransaction Timeline