Transactions
List Transactions

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

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

1curl -X GET 'https://api.budpay.com/api/v2/transaction' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "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}
Powered byXendr

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes

Query Parameters (Optional)

ParameterTypeDescriptionDefault
pageIntegerPage number for pagination1
per_pageIntegerNumber of transactions per page50
statusStringFilter by status: success, pending, failedAll
currencyStringFilter by currency: NGN, USD, GHS, KESAll
channelStringFilter by channel: card, transfer, mobile_moneyAll

Response Fields

Root Level
FieldTypeDescription
statusBooleanIndicates if the request was successful
messageStringResponse message
dataArrayArray of transaction objects
total_countIntegerTotal number of transactions
Transaction Object
FieldTypeDescription
idIntegerInternal transaction ID
currencyStringCurrency code: NGN, USD, GHS, KES
amountStringTotal amount including fees
referenceStringUnique transaction reference
ip_addressStringCustomer's IP address (if available)
channelStringPayment channel: card, transfer, mobile_money, or null
domainStringEnvironment: test or live
feesStringTransaction processing fees
planStringSubscription plan ID (if applicable)
requested_amountStringOriginal amount before fees
statusStringTransaction status: success, pending, failed
gatewayStringPayment gateway used (e.g., Interswitch, Wema)
created_atStringTimestamp when transaction was created
paid_atStringTimestamp when payment was completed
Customer Object
FieldTypeDescription
idIntegerCustomer ID in BudPay system
first_nameStringCustomer's first name
last_nameStringCustomer's last name
emailStringCustomer's email address
phoneStringCustomer's phone number
customer_codeStringUnique customer code
domainStringCustomer domain: test or live
metadataStringAdditional customer metadata
statusStringCustomer account status

Pagination

Use query parameters to paginate through transactions:

Example with Pagination

Endpoint: GET https://api.budpay.com/api/v2/transaction?page=2&per_page=20

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

Filtering Transactions

Filter transactions by status, currency, or channel:

Filter by Status

Endpoint: GET https://api.budpay.com/api/v2/transaction?status=success

1curl -X GET 'https://api.budpay.com/api/v2/transaction?status=success' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr
Filter by Currency

Endpoint: GET https://api.budpay.com/api/v2/transaction?currency=NGN

1curl -X GET 'https://api.budpay.com/api/v2/transaction?currency=NGN' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr
Filter by Channel

Endpoint: GET https://api.budpay.com/api/v2/transaction?channel=card

1curl -X GET 'https://api.budpay.com/api/v2/transaction?channel=card' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr
Multiple Filters

Endpoint: GET https://api.budpay.com/api/v2/transaction?status=success&currency=NGN&channel=card

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

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.

  1. Use Pagination: Don't fetch all transactions at once. Use pagination for better performance.

  2. Apply Filters: Filter by status, currency, or channel to get only the data you need.

  3. Cache Results: Cache transaction lists when appropriate to reduce API calls.

  4. Handle Nulls: Many fields can be null. Always check before using values.

  5. Monitor Total Count: Use total_count to track the total number of transactions.

  6. Implement Retry Logic: Add retry logic for failed requests.

  7. Regular Reconciliation: Regularly fetch and reconcile transactions with your records.

  8. Store Locally: Consider storing transaction data locally for faster access and reporting.

Next Steps

OverviewFetch Transaction Details