Verify Transfer

Retrieve detailed information about a specific payout/transfer using its unique reference ID. This endpoint allows you to check transfer status and view complete transfer details.

Endpoint

GET https://api.budpay.com/api/v2/payout/:reference

Sample Request

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

Sample Response

{
    "status": true,
    "message": "Payout retrieved",
    "data": {
        "id": 15,
        "reference": "trf_11044f068j1604",
        "sessionid": null,
        "currency": "NGN",
        "amount": "100",
        "fee": "10",
        "bank_code": "000013",
        "bank_name": "GUARANTY TRUST BANK",
        "account_number": "0050883605",
        "account_name": "OYENIYI TOLULOPE OYEBIYI",
        "narration": "Test transfer",
        "domain": "test",
        "status": "pending",
        "subaccount": null,
        "created_at": "2022-03-29T01:51:01.000000Z",
        "updated_at": "2022-03-29T01:51:01.000000Z"
    }
}

Try it out

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`reference`	String	Yes	Unique transfer reference ID (e.g., `trf_11044f068j1604`)

Header Parameters

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

Response Fields

Field	Type	Description
`status`	Boolean	Indicates if request was successful
`message`	String	Response message
`data.id`	Integer	Internal transfer ID
`data.reference`	String	Unique transfer reference ID
`data.sessionid`	String	Session ID (if applicable)
`data.currency`	String	Transfer currency (NGN, KES, GHS)
`data.amount`	String	Transfer amount
`data.fee`	String	Transaction fee charged
`data.bank_code`	String	Recipient bank code
`data.bank_name`	String	Recipient bank name
`data.account_number`	String	Recipient account number
`data.account_name`	String	Verified account holder name
`data.narration`	String	Transfer description
`data.domain`	String	Environment: `test` or `live`
`data.status`	String	Transfer status
`data.subaccount`	String	Subaccount ID (if applicable)
`data.created_at`	String	Transfer creation timestamp
`data.updated_at`	String	Last update timestamp

Transfer Status Values

Status	Description	Action Required
`pending`	Transfer is being processed	Wait for completion or webhook notification
`success`	Transfer completed successfully	No action required
`failed`	Transfer failed	Check error details and retry if needed
`reversed`	Transfer was reversed	Contact support if unexpected

Error Handling

401 Unauthorized

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

404 Not Found

{
    "status": false,
    "message": "Payout not found"
}

422 Validation Error

{
    "status": false,
    "message": "Invalid reference format"
}

Best Practices

Tip: Always verify transfer status after initiating payouts to ensure successful completion before updating your records.

Store References: Always save transfer reference IDs for future verification
Status Monitoring: Check transfer status periodically for pending transfers
Webhook Integration: Use webhooks for real-time status updates instead of polling
Error Handling: Implement proper handling for failed or reversed transfers
Reconciliation: Use this endpoint for daily reconciliation of transfer batches
Retry Logic: For pending transfers, wait before retrying or checking status again

Verification Workflow

💡

Best Practice: Combine webhook notifications with periodic verification checks for robust transfer tracking.

Initiate Transfer: Create single or bulk payout and store reference
Immediate Check: Optionally verify transfer was queued successfully
Webhook Notification: Receive real-time updates via webhook
Periodic Verification: Check pending transfers periodically
Final Reconciliation: Verify all transfers at end of day/batch

Security Considerations

⚠️

Security: Never expose transfer references or API responses containing account details in client-side code or logs.

Server-Side Only: Always verify transfers from your secure backend
HTTPS Only: Use secure connections for all verification requests
Data Privacy: Handle account details securely and comply with data protection regulations
Access Control: Restrict access to transfer verification endpoints

Next Steps

Single Payout - Initiate individual bank transfers
Bulk Payout - Process multiple transfers in batch
Transaction Verification - Verify payment transactions
Webhooks - Set up real-time status notifications

Bulk Transfer Payout Fees