Transactions
Search Transaction

Search Transaction

Search for transactions using various identifiers such as transaction reference, session ID, account number, or card PAN. This powerful search endpoint helps you quickly locate specific transactions across your payment records.

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

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

Sample Response

{
    "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"
            }
        }
    ]
}
Try it out

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes

URL Parameters

ParameterTypeRequiredDescription
searchStringYesSearch term: transaction reference, session ID, account number, or card PAN

Searchable Fields

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

Search TypeExampleDescription
Transaction ReferenceBUD_1673600359168063493Unique transaction reference generated by BudPay
Session IDsess_abc123xyzPayment session identifier
Account Number1234567890Virtual account number for bank transfers
Card PAN408408******4081Masked or partial card number

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

Response Fields

Transaction Data
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
typeStringTransaction type (e.g., transaction)
domainStringEnvironment: test or live
feesStringTransaction processing fees
planStringSubscription plan ID (if applicable)
requested_amountStringOriginal amount before fees
statusStringTransaction status: success, pending, failed
card_attemptIntegerNumber of card authorization attempts
split_codeStringSplit payment code (if applicable)
messageStringAdditional transaction message
gatewayStringPayment gateway used (e.g., Wema)
transfer_detailsObjectBank transfer specific details
webhook_statusStringWebhook delivery status: sent, pending, failed
webhook_urlStringURL where webhook was sent
webhook_responseStringResponse from webhook endpoint
metadataStringCustom metadata attached to transaction
created_atStringTimestamp when transaction was created
paid_atStringTimestamp when payment was completed
Customer Data
FieldTypeDescription
idIntegerCustomer ID in BudPay system
first_nameStringCustomer's first name
last_nameStringCustomer's last name
emailStringCustomer's email address
phoneStringCustomer's phone number
domainStringCustomer domain: test or live
customer_codeStringUnique customer code
metadataStringAdditional customer metadata
statusStringCustomer 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.

  1. Use Transaction References: Most reliable identifier for unique transaction lookup

  2. URL Encode Special Characters: Ensure search terms are properly URL encoded

  3. Handle Arrays: Always expect the response data to be an array, even for single results

  4. Validate Results: Check that returned transactions match your expected criteria

  5. Implement Caching: Cache frequently searched transactions to reduce API calls

  6. Log Searches: Keep logs of search queries for debugging and audit purposes

  7. Error Handling: Always implement robust error handling for search failures

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.

  • Server-Side Only: Perform searches from your secure backend server
  • Sensitive Data: Be careful when searching by card PAN or account numbers
  • Access Control: Limit search functionality to authorized personnel
  • Audit Logs: Maintain logs of who searched for what transactions
  • Data Protection: Handle search results according to data protection regulations

Next Steps

Fetch Transaction DetailsTransaction Statement