Get Transaction by Reference

Retrieve a specific transaction using its unique reference number.

Endpoint

GET https://api.cashonrails.com/api/v1/transaction-reference/{reference}

Headers

Path Parameters

Sample Request

GET https://api.cashonrails.com/api/v1/transaction-reference/{reference}

Sample cURL Request

curl -X GET "https://api.cashonrails.com/api/v1/transaction-reference/{reference}" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json"

Sample Response

{
    "status": true,
    "message": "Transactions retrieved",
    "data": {
        "id": 204404,
        "domain": "live",
        "status": "success",
        "reference": "100004251010120646142810790227",
        "amount": "1000",
        "gateway_response": null,
        "paid_at": "2025-10-10 13:07:03",
        "created_at": "2025-10-10T12:07:03.000000Z",
        "channel": "banktransfer",
        "currency": "NGN",
        "ip_address": "162.158.230.113"
    },
    "log": {
        "time_spent": 0,
        "attempts": 0,
        "authentication": null,
        "errors": 0,
        "success": true,
        "channel": "banktransfer",
        "history": []
    },
    "fees": "10",
    "customer": {
        "id": 998,
        "customer_code": "CUS_yhlknqpurtkar5p",
        "first_name": "Sunday",
        "last_name": "Akinlabi",
        "email": "akinlabisamson15@gmail.com",
        "phone": "07040237649",
        "metadata": "{}"
    },
    "plan": null,
    "paid_at": "2025-10-10 13:07:03",
    "created_at": "2025-10-10T12:07:03.000000Z",
    "requested_amount": "1000"
}

Use Cases

This endpoint is particularly useful when you need to:

• Track payments - Look up transactions using the reference provided to customers
• Handle webhooks - Verify transaction details when receiving webhook notifications
• Customer support - Help customers check their payment status using their reference
• Reconciliation - Match transactions with your internal records

Response Fields

The response structure is identical to the Get Transaction by ID endpoint, containing:

• Transaction Data - Core transaction information
• Log Information - Processing details and history
• Customer Information - Complete customer details
• Fees - Transaction fees charged
• Timestamps - Creation and payment completion times

Transaction Reference Format

Transaction references in CashOnRails follow this pattern:

• Length: 30 characters
• Format: Numeric string
• Example: 100004251010120646142810790227
• Uniqueness: Each reference is globally unique across all transactions

Error Responses

Transaction Not Found

{
    "status": false,
    "message": "Transaction not found",
    "data": null
}

This error occurs when:

• The reference doesn’t exist in your account
• The reference format is invalid
• The transaction belongs to a different merchant account

Invalid Reference Format

{
    "status": false,
    "message": "Invalid reference format",
    "data": null
}

This error occurs when the reference parameter doesn’t match the expected format.

Best Practices

1. Store References - Always store transaction references in your database for future lookups
2. Error Handling - Implement proper error handling for cases where references might not exist
3. Rate Limiting - Be mindful of API rate limits when making multiple reference lookups
4. Webhook Integration - Use this endpoint to verify transactions received via webhooks

Use this endpoint to quickly retrieve transaction details using the reference number, which is particularly useful for customer support and webhook verification scenarios.