Search Transaction

Search for transactions using various identifiers such as transaction reference, session ID, account number, or card PAN. Use it to locate a transaction when you only have one of these identifiers.

Endpoint

GET https://api.budpay.com/api/v2/transaction_query/{search}

Replace {search} with your search term (reference, session ID, account number, or card PAN).

Sample Request

Endpoint: GET https://api.budpay.com/api/v2/transaction_query/BUD_1673600359168063493

1curl -X GET 'https://api.budpay.com/api/v2/transaction_query/BUD_1673600359168063493' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'

{  "status": true,  "message": "Transactions retrieved",  "data": [    {      "id": 1404612,      "currency": "NGN",      "amount": "550",      "reference": "BUD_1673600359168063493",      "ip_address": null,      "channel": "transfer",      "type": "transaction",      "domain": "live",      "fees": "50",      "plan": null,      "requested_amount": "500",      "status": "success",      "card_attempt": 0,      "split_code": null,      "message": null,      "gateway": "Wema",      "transfer_details": null,      "webhook_status": "sent",      "webhook_url": "https://webhook.site/6809bce0-6760-4e63-b3fd-1e545cec8958",      "webhook_response": "",      "metadata": "",      "created_at": "2023-01-13T08:59:26.000000Z",      "paid_at": "2023-01-13 10:06:29",      "customer": {        "id": 627321,        "first_name": "Francis",        "last_name": "Obadiah",        "email": "francis@budpay.com",        "phone": "",        "domain": "live",        "customer_code": "CUS_0q2htds3kf3zzrb",        "metadata": "{}",        "status": "active"      }    }  ]}

Request Parameters

Header Parameters

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

URL Parameters

Parameter	Type	Required	Description
`search`	String	Yes	Search term: transaction reference, session ID, account number, or card PAN

Searchable Fields

You can search for transactions using any of the following identifiers:

Search Type	Example	Description
Transaction Reference	`BUD_1673600359168063493`	Unique transaction reference generated by BudPay
Session ID	`sess_abc123xyz`	Payment session identifier
Account Number	`1234567890`	Virtual account number for bank transfers
Card PAN	`408408******4081`	Masked or partial card number

Note: The search is flexible and can match partial or full identifiers across different transaction types.

Response Fields

Transaction Data

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`
`type`	String	Transaction type (e.g., `transaction`)
`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`
`card_attempt`	Integer	Number of card authorization attempts
`split_code`	String	Split payment code (if applicable)
`message`	String	Additional transaction message
`gateway`	String	Payment gateway used (e.g., `Wema`)
`transfer_details`	Object	Bank transfer specific details
`webhook_status`	String	Webhook delivery status: `sent`, `pending`, `failed`
`webhook_url`	String	URL where webhook was sent
`webhook_response`	String	Response from webhook endpoint
`metadata`	String	Custom metadata attached to transaction
`created_at`	String	Timestamp when transaction was created
`paid_at`	String	Timestamp when payment was completed

Customer Data

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
`domain`	String	Customer domain: `test` or `live`
`customer_code`	String	Unique customer code
`metadata`	String	Additional customer metadata
`status`	String	Customer account status

Error Handling

404 Not Found

{
    "status": false,
    "message": "No transactions found"
}

Solution: The search term doesn't match any transactions. Verify the identifier is correct.

401 Unauthorized

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

Best Practices

Tip: Use specific search terms for faster and more accurate results. Transaction references are the most reliable identifiers.

Use Transaction References: Most reliable identifier for unique transaction lookup
URL Encode Special Characters: Ensure search terms are properly URL encoded
Handle Arrays: Always expect the response data to be an array, even for single results
Validate Results: Check that returned transactions match your expected criteria

Security Considerations

⚠️

Security: Never expose card PANs or sensitive customer data in logs or client-side code. Use masked or partial numbers when displaying search results.

Sensitive Data: Be careful when searching by card PAN or account numbers

Next Steps

Fetch Transaction - Get detailed transaction information
List Transactions - Retrieve multiple transactions
Filter Transactions - Filter by status, currency, or channel
Webhooks - Receive real-time transaction notifications

Fetch Transaction Details Transaction Statement