API Basics

The BudPay API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP methods, status codes, and Bearer authentication. This page covers the conventions shared by every endpoint.

Easy to Integrate. Easy to Test.

The following tools help you build and test your integration:

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:

cURLJavascriptPythonGo

More

cURL

More

Try it

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

Powered by

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?