Transactions
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

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

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

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes

URL Parameters

ParameterDescriptionRequired
idTransaction reference IDYes

Response Fields

Transaction Data
FieldTypeDescription
idIntegerInternal transaction ID
domainStringEnvironment: test or live
statusStringTransaction status: pending, success, failed
referenceStringUnique transaction reference
amountStringTransaction amount
gateway_responseStringResponse message from payment gateway
paid_atStringTimestamp when payment was completed
created_atStringTimestamp when transaction was initiated
channelStringPayment channel used: card, bank_transfer, mobile_money
currencyStringCurrency code: NGN, USD, GHS, KES
ip_addressStringCustomer's IP address
requested_amountStringOriginal requested amount
Transaction Log
FieldTypeDescription
time_spentIntegerTime in milliseconds for transaction completion
attemptsIntegerNumber of payment attempts
authenticationStringAuthentication method used (if any)
errorsIntegerNumber of errors encountered
successBooleanWhether transaction was successful
channelStringPayment channel used
historyArrayArray of transaction events

History Object:

FieldTypeDescription
typeStringEvent type: action, success, error
messageStringDescription of the event
timeIntegerTime in milliseconds when event occurred
Customer Data
FieldTypeDescription
idIntegerCustomer ID in BudPay system
customer_codeStringUnique customer code
first_nameStringCustomer's first name
last_nameStringCustomer's last name
emailStringCustomer's email address
phoneStringCustomer's phone number
metadataStringAdditional customer metadata
Other Fields
FieldTypeDescription
feesStringTransaction processing fees
planObjectSubscription plan details (if applicable)

Transaction Statuses

StatusDescription
pendingTransaction initiated but not yet completed
successPayment completed successfully
failedTransaction failed or was declined
abandonedCustomer 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.

  1. Verify Before Fulfillment: Always fetch transaction details from the API before providing goods or services.

  2. Store References: Keep transaction references in your database for easy tracking and reconciliation.

  3. Check Status: Verify the status field is success before proceeding with order fulfillment.

  4. Use Webhooks: Implement webhooks for real-time payment notifications, then verify via API.

  5. Handle Errors: Implement proper error handling for failed or invalid transactions.

  6. Logging: Log transaction details for audit trails and customer support.

  7. 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 TransactionsSearch Transaction