List Transactions

Retrieve a list of all transactions associated with your BudPay account. This endpoint returns paginated transaction data including payment details, customer information, and transaction status.

Endpoint

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

Sample Request

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

Sample Response

{
    "status": true,
    "message": "Transactions retrieved",
    "data": [
        {
            "id": 44,
            "currency": "NGN",
            "amount": "2000",
            "reference": "16434005201755524296",
            "ip_address": null,
            "channel": null,
            "domain": "test",
            "fees": null,
            "plan": null,
            "requested_amount": "2000",
            "status": "success",
            "gateway": null,
            "created_at": "2022-01-28T20:08:40.000000Z",
            "paid_at": "2022-01-28 20:11:51",
            "customer": {
                "id": 3,
                "first_name": null,
                "last_name": null,
                "email": "customer@email.com",
                "phone": null,
                "customer_code": "CUS_3hqlcizuoffygev",
                "domain": "test",
                "metadata": "{}",
                "status": "active"
            }
        },
        {
            "id": 45,
            "currency": "NGN",
            "amount": "2300",
            "reference": "1643400746693960617",
            "ip_address": null,
            "channel": null,
            "domain": "test",
            "fees": null,
            "plan": null,
            "requested_amount": "2300",
            "status": "success",
            "gateway": null,
            "created_at": "2022-01-28T20:12:26.000000Z",
            "paid_at": "2022-01-28 20:14:30",
            "customer": {
                "id": 3,
                "first_name": null,
                "last_name": null,
                "email": "customer@email.com",
                "phone": null,
                "customer_code": "CUS_3hqlcizuoffygev",
                "domain": "test",
                "metadata": "{}",
                "status": "active"
            }
        },
        {
            "id": 46,
            "currency": "NGN",
            "amount": "300",
            "reference": "1643446267206306434",
            "ip_address": null,
            "channel": "card",
            "domain": "test",
            "fees": null,
            "plan": null,
            "requested_amount": "300",
            "status": "success",
            "gateway": "Interswitch",
            "created_at": "2022-01-29T08:51:07.000000Z",
            "paid_at": "2022-01-29 19:52:58",
            "customer": {
                "id": 3,
                "first_name": null,
                "last_name": null,
                "email": "customer@email.com",
                "phone": null,
                "customer_code": "CUS_3hqlcizuoffygev",
                "domain": "test",
                "metadata": "{}",
                "status": "active"
            }
        },
        {
            "id": 47,
            "currency": "NGN",
            "amount": "20000",
            "reference": "61e469c330c2bb",
            "ip_address": null,
            "channel": null,
            "domain": "test",
            "fees": null,
            "plan": null,
            "requested_amount": "20000",
            "status": "pending",
            "gateway": null,
            "created_at": "2022-01-29T23:57:40.000000Z",
            "paid_at": null,
            "customer": {
                "id": 4,
                "first_name": null,
                "last_name": null,
                "email": "customer1@budpay.com",
                "phone": null,
                "customer_code": "CUS_ig2yjfnhtphlgt0",
                "domain": "test",
                "metadata": "{}",
                "status": "active"
            }
        },
        {
            "id": 48,
            "currency": "NGN",
            "amount": "20000",
            "reference": "61e469c330c2bc",
            "ip_address": null,
            "channel": null,
            "domain": "test",
            "fees": null,
            "plan": null,
            "requested_amount": "20000",
            "status": "pending",
            "gateway": null,
            "created_at": "2022-01-31T16:22:03.000000Z",
            "paid_at": null,
            "customer": {
                "id": 4,
                "first_name": null,
                "last_name": null,
                "email": "customer1@budpay.com",
                "phone": null,
                "customer_code": "CUS_ig2yjfnhtphlgt0",
                "domain": "test",
                "metadata": "{}",
                "status": "active"
            }
        }
    ],
    "total_count": 5
}

Try it out

Request Parameters

Header Parameters

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

Query Parameters (Optional)

Parameter	Type	Description	Default
`page`	Integer	Page number for pagination	1
`per_page`	Integer	Number of transactions per page	50
`status`	String	Filter by status: `success`, `pending`, `failed`	All
`currency`	String	Filter by currency: `NGN`, `USD`, `GHS`, `KES`	All
`channel`	String	Filter by channel: `card`, `transfer`, `mobile_money`	All

Response Fields

Root Level

Field	Type	Description
`status`	Boolean	Indicates if the request was successful
`message`	String	Response message
`data`	Array	Array of transaction objects
`total_count`	Integer	Total number of transactions

Transaction Object

Field	Type	Description
`id`	Integer	Internal transaction ID
`currency`	String	Currency code: `NGN`, `USD`, `GHS`, `KES`
`amount`	String	Total amount including fees
`reference`	String	Unique transaction reference
`ip_address`	String	Customer's IP address (if available)
`channel`	String	Payment channel: `card`, `transfer`, `mobile_money`, or `null`
`domain`	String	Environment: `test` or `live`
`fees`	String	Transaction processing fees
`plan`	String	Subscription plan ID (if applicable)
`requested_amount`	String	Original amount before fees
`status`	String	Transaction status: `success`, `pending`, `failed`
`gateway`	String	Payment gateway used (e.g., `Interswitch`, `Wema`)
`created_at`	String	Timestamp when transaction was created
`paid_at`	String	Timestamp when payment was completed

Customer Object

Field	Type	Description
`id`	Integer	Customer ID in BudPay system
`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
`customer_code`	String	Unique customer code
`domain`	String	Customer domain: `test` or `live`
`metadata`	String	Additional customer metadata
`status`	String	Customer account status

Pagination

Use query parameters to paginate through transactions:

Example with Pagination

curl "https://api.budpay.com/api/v2/transaction?page=2&per_page=20" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Filtering Transactions

Filter transactions by status, currency, or channel:

Filter by Status

curl "https://api.budpay.com/api/v2/transaction?status=success" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Filter by Currency

curl "https://api.budpay.com/api/v2/transaction?currency=NGN" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Filter by Channel

curl "https://api.budpay.com/api/v2/transaction?channel=card" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Multiple Filters

curl "https://api.budpay.com/api/v2/transaction?status=success&currency=NGN&channel=card" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Error Handling

401 Unauthorized

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

Solution: Check that your API key is valid and properly formatted.

500 Internal Server Error

{
    "status": false,
    "message": "An error occurred"
}

Solution: Contact BudPay support if the issue persists.

Best Practices

Tip: Use pagination and filters to reduce response size and improve performance, especially when dealing with large transaction volumes.

Use Pagination: Don't fetch all transactions at once. Use pagination for better performance.
Apply Filters: Filter by status, currency, or channel to get only the data you need.
Cache Results: Cache transaction lists when appropriate to reduce API calls.
Handle Nulls: Many fields can be null. Always check before using values.
Monitor Total Count: Use total_count to track the total number of transactions.
Implement Retry Logic: Add retry logic for failed requests.
Regular Reconciliation: Regularly fetch and reconcile transactions with your records.
Store Locally: Consider storing transaction data locally for faster access and reporting.

Next Steps

Fetch Transaction - Get detailed information about a specific transaction
Search Transactions - Search by reference, account, or card
Transaction Filters - Advanced filtering options
Webhooks - Receive real-time transaction notifications

Overview Fetch Transaction Details