Fetch Transaction Details

Fetch Transaction

Retrieve detailed information about a specific transaction using its unique reference ID. This endpoint returns comprehensive transaction data including payment status, customer information, transaction logs, and more.

Endpoint

GET https://api.budpay.com/api/v2/transaction/:id

Replace :id with the transaction reference you want to retrieve.

Sample Request

curl https://api.budpay.com/api/v2/transaction/61e46a7a0e69011 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Sample Response

{
    "status": true,
    "message": "Transactions retrieved",
    "data": {
        "id": 4,
        "domain": "test",
        "status": "pending",
        "reference": "61e46a7a0e69011",
        "amount": "2",
        "gateway_response": null,
        "paid_at": "2022-01-18 13:47:02",
        "created_at": "2022-01-16T18:56:58.000000Z",
        "channel": "card",
        "currency": "USD",
        "ip_address": "197.211.43.98"
    },
    "log": {
        "time_spent": 192,
        "attempts": 1,
        "authentication": null,
        "errors": 0,
        "success": true,
        "channel": "card",
        "history": [
            {
                "type": "action",
                "message": "Attempted to pay with card",
                "time": 191
            },
            {
                "type": "success",
                "message": "Successfully paid with card",
                "time": 192
            }
        ]
    },
    "fees": null,
    "customer": {
        "id": 1,
        "customer_code": "cus78359iu54riej",
        "first_name": "Budpay",
        "last_name": "Checkout",
        "email": "budpay@checkout",
        "phone": null,
        "metadata": ""
    },
    "plan": null,
    "paid_at": "2022-01-18 13:47:02",
    "created_at": "2022-01-16T18:56:58.000000Z",
    "requested_amount": "2"
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes

URL Parameters

Parameter	Description	Required
`id`	Transaction reference ID	Yes

Response Fields

Transaction Data

Field	Type	Description
`id`	Integer	Internal transaction ID
`domain`	String	Environment: `test` or `live`
`status`	String	Transaction status: `pending`, `success`, `failed`
`reference`	String	Unique transaction reference
`amount`	String	Transaction amount
`gateway_response`	String	Response message from payment gateway
`paid_at`	String	Timestamp when payment was completed
`created_at`	String	Timestamp when transaction was initiated
`channel`	String	Payment channel used: `card`, `bank_transfer`, `mobile_money`
`currency`	String	Currency code: `NGN`, `USD`, `GHS`, `KES`
`ip_address`	String	Customer's IP address
`requested_amount`	String	Original requested amount

Transaction Log

Field	Type	Description
`time_spent`	Integer	Time in milliseconds for transaction completion
`attempts`	Integer	Number of payment attempts
`authentication`	String	Authentication method used (if any)
`errors`	Integer	Number of errors encountered
`success`	Boolean	Whether transaction was successful
`channel`	String	Payment channel used
`history`	Array	Array of transaction events

History Object:

Field	Type	Description
`type`	String	Event type: `action`, `success`, `error`
`message`	String	Description of the event
`time`	Integer	Time in milliseconds when event occurred

Customer Data

Field	Type	Description
`id`	Integer	Customer ID in BudPay system
`customer_code`	String	Unique customer code
`first_name`	String	Customer's first name
`last_name`	String	Customer's last name
`email`	String	Customer's email address
`phone`	String	Customer's phone number
`metadata`	String	Additional customer metadata

Other Fields

Field	Type	Description
`fees`	String	Transaction processing fees
`plan`	Object	Subscription plan details (if applicable)

Transaction Statuses

Status	Description
`pending`	Transaction initiated but not yet completed
`success`	Payment completed successfully
`failed`	Transaction failed or was declined
`abandoned`	Customer left without completing payment

Error Handling

404 Not Found

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

Solution: Verify the transaction reference is correct and exists in your system.

401 Unauthorized

{
    "status": false,
    "message": "Authentication failed"
}

Solution: Check that your API key is valid and properly formatted in the Authorization header.

Best Practices

Always verify transactions server-side before fulfilling orders. Never rely solely on client-side callbacks.

Verify Before Fulfillment: Always fetch transaction details from the API before providing goods or services.
Store References: Keep transaction references in your database for easy tracking and reconciliation.
Check Status: Verify the status field is success before proceeding with order fulfillment.
Use Webhooks: Implement webhooks for real-time payment notifications, then verify via API.
Handle Errors: Implement proper error handling for failed or invalid transactions.
Logging: Log transaction details for audit trails and customer support.
Reconciliation: Regularly reconcile your records with BudPay transaction data.

Security Considerations

⚠️

Never expose your secret API key in client-side code. Always make API calls from your secure backend server.

Server-Side Only: Fetch transaction details only from your backend server
Validate Data: Always verify transaction amounts and references match your records
Secure Storage: Store API keys securely using environment variables
HTTPS Only: Always use HTTPS for API requests
Rate Limiting: Implement rate limiting to prevent abuse

Next Steps

List All Transactions - Retrieve multiple transactions
Transaction Filters - Filter by date, status, etc.
Webhooks Setup - Receive real-time notifications
Refunds - Process transaction refunds

List Transactions Search Transaction