API Basics

Build powerful payment experiences with BudPay's simple, predictable, and well-documented APIs. Whether you are collecting payments, sending payouts, or managing customers, our APIs are designed to get you up and running in minutes.

Easy to Integrate. Easy to Test.

We built BudPay APIs with developers in mind. Here is what makes integration effortless:

Authentication

Authenticate your requests with a simple Bearer token. Include your secret key in the Authorization header:

Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

For Payouts and Bills Payment endpoints, include an additional encryption header:

Authorization: Bearer YOUR_SECRET_KEY
Encryption: Signature_HMAC-SHA-512
Content-Type: application/json

HTTP Methods

Request & Response Format

Every request and response uses JSON. Here is what a typical exchange looks like:

Your Request:

{
    "email": "customer@example.com",
    "amount": "10000",
    "currency": "NGN",
    "reference": "BUD_1234567890"
}

Our Response:

{
    "success": true,
    "message": "Transaction initialized successfully",
    "data": {
        "id": 1404612,
        "reference": "BUD_1234567890",
        "amount": "10000",
        "status": "success"
    }
}

Understanding the Response

Status Codes

We use standard HTTP codes so you always know what happened:

Success

Client Errors

Server Errors

Common Errors & Quick Fixes

Missing Fields

{
    "success": false,
    "message": "Validation error",
    "errors": {
        "email": ["The email field is required"],
        "amount": ["The amount field is required"]
    }
}

Fix: Include all required parameters in your request.

Authentication Failed

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

Fix: Double-check your API key and ensure it is in the Authorization header.

Duplicate Reference

{
    "success": false,
    "message": "Reference already existed"
}

Fix: Generate a unique reference for every transaction.

Invalid Signature

{
    "success": false,
    "message": "Invalid Signature. Intrusion detected. Failed [A.A.E.101]"
}

Fix: For Payout and Bills endpoints, ensure you are generating the HMAC-SHA-512 signature correctly with your secret key.

Service Unavailable

{
    "success": false,
    "message": "Service currently not available"
}

Fix: Wait a few moments and retry. Check our status page if the issue persists.

Try It Right Now

Built-in API Tester

Every endpoint in our documentation includes an interactive tester. No setup needed, just:

1. Navigate to any API endpoint page
2. Scroll to the "Try it out" section
3. Enter your test API key
4. Modify any parameters
5. Click "Send Request"
6. Copy the working code in your preferred language

Here is a live example. Try fetching the bank list:

APIs Collection for Postman

Prefer testing in Postman? We have got you covered:

Your First API Call

Ready to try? Here is a quick test using cURL:

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

Or initialize your first payment:

curl -X POST https://api.budpay.com/api/v2/transaction/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "amount": "10000",
    "currency": "NGN",
    "callback": "https://yourwebsite.com/callback"
  }'

Best Practices

Security First

• Never expose secret keys in frontend code
• Store keys in environment variables
• Validate webhooks before processing

Build for Reliability

• Use unique references for every transaction
• Implement retries with exponential backoff
• Log everything: requests and responses

Verify, Do Not Assume

• Always verify transaction status via API
• Check both HTTP status and success field
• Handle errors gracefully with user-friendly messages

What is Next?