Bank Transfer – BudPay

Server to Server (Bank Transfer)

The Bank Transfer API generates a bank account for a single transaction. Your customer pays by transferring the amount to that account from any bank app, and BudPay notifies you when the funds arrive.

How it works

Generate account details. Call the initialize endpoint to create a bank account for the transaction.
Show the details to the customer. The customer transfers the exact amount to the generated account.
Receive a webhook. BudPay notifies your webhook URL when the transfer is received.
Verify the payment. Confirm the status with the verify endpoint before you give value.

Step 1: Generate Account Details

Call the initialize endpoint from your server with the customer's details and the amount to collect.

Endpoint: POST https://api.budpay.com/api/s2s/banktransfer/initialize

1curl -X POST 'https://api.budpay.com/api/s2s/banktransfer/initialize' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "email": "test@test.com",6  "amount": "100",7  "currency": "NGN",8  "reference": "1253627873656276350",9  "name": "Business Name / Firstname lastname"10}'

{  "status": true,  "message": "Account generated successfully",  "data": {    "account_name": "Business Name / Firstname lastname",    "account_number": "1014692362",    "bank_name": "BudPay Bank"  }}

Request Body

Parameter	Type	Required	Description
`email`	`string`	Yes	Customer's email address.
`amount`	`string`	Yes	Amount to collect.
`currency`	`string`	Yes	Currency of the payment.
`reference`	`string`	Yes	Unique reference for the transaction.
`name`	`string`	Yes	Name shown on the generated account, such as your business name or the customer's name.

Step 2: Show the Account Details

Display account_number, bank_name and account_name from the response in your checkout, together with the exact amount to transfer. The customer completes the transfer from their bank app.

Step 3: Handle the Webhook

When the transfer is received, BudPay sends a transaction webhook to the URL configured in your BudPay dashboard. Use it to update the order in your system, then verify the transaction before you give value.

The payload uses the standard transaction webhook format. The example below is from a card payment; the channel field shows the payment method used.

{
    "notify": "transaction",
    "notifyType": "successful",
    "data": {
        "id": 1050471,
        "currency": "USD",
        "amount": "5.22",
        "reference": "482208088163205800",
        "ip_address": null,
        "channel": "card",
        "type": "transaction",
        "domain": "live",
        "fees": "0.19836",
        "plan": null,
        "requested_amount": "5.22",
        "status": "success",
        "card_attempt": 1,
        "settlement_batchid": null,
        "message": "Approved",
        "metadata": "MID: DPPSPBDNG|15173|5399|CAPTURED|Approved|SUCCESS|520149xxxxxx1019|MASTERCARD|2022-08-08T12:59:17.516Z|2022-08-08|175714|USD|222012015173|13203834|UBAS3I01",
        "created_at": "2022-08-08T12:58:09.000000Z",
        "updated_at": "2022-08-08T12:59:23.000000Z",
        "paid_at": "2022-08-08 13:59:23",
        "customer": {
            "id": 427351,
            "first_name": null,
            "last_name": null,
            "email": "customer@example.com",
            "phone": null,
            "domain": "live",
            "customer_code": "CUS_6kj536tc0kx9brb",
            "metadata": "{}",
            "status": "active"
        }
    }
}

Verifying Transactions

Call the Verify Transaction API with the transaction reference:

GET https://api.budpay.com/api/v2/transaction/verify/:reference

Example Request:

Endpoint: GET https://api.budpay.com/api/v2/transaction/verify/BUD_1673600359168063493

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

{  "status": true,  "message": "Transaction verified successfully",  "data": {    "currency": "NGN",    "amount": "550",    "reference": "BUD_1673600359168063493",    "status": "success",    "message": "Payment successful",    "customer": {      "email": "customer@email.com"    }  }}

Always verify transactions on your server before fulfilling orders. Never rely solely on client-side callbacks or redirects.

Verification Workflow:

Receive callback/webhook with transaction reference
Call Verify API (server-side)
Check status === "success"
Verify amount matches expected
Fulfill order/deliver service

Learn more about verifying transactions.

Cards V2 Mobile Money