BudPay Inline (Popup)

BudPay Inline lets you accept payments on your website through a secure payment modal. Customers pay without leaving your site, and you add it with a single script tag and a few lines of JavaScript.

How it works

1. Load the library. Add the BudPay script to your checkout page.
2. Open the payment modal. When the customer clicks your pay button, call BudPayCheckout() or BudPayCheckoutWithAccessCode().
3. The customer pays. BudPay collects and processes the payment inside the modal.
4. Handle the result. If you set a callback_url, BudPay redirects the customer there with reference and status as query parameters. Otherwise, BudPay calls your callback function with the same values.
5. Verify the payment. Confirm the result on your server with the Verify Transaction API before you give value.

Choosing an integration method

BudPay Inline supports two integration methods. Both open the same secure payment modal; they differ in where the transaction is created.

Live demo

The example below shows the payment modal on a basic checkout page. You can also try it on the BudPay checkout demo (opens in a new tab).

1. BudPayCheckout

BudPayCheckout opens the payment modal using your public key and a transaction payload defined in your frontend code. It requires no server-side work, which makes it the fastest way to start accepting payments.

Add the library

Include the library on your checkout page with a script tag:

<script src="https://inlinepay.budpay.com/budpay-inline-custom.js"></script>

Add a payment button

Call your payment function from the button's onclick handler. This example uses a function named payWithBudPay():

<button onclick="payWithBudPay()">Pay with BudPay</button>

Open the payment modal

Inside payWithBudPay(), call BudPayCheckout with your public key and the transaction details:

function payWithBudPay() {
    BudPayCheckout({
        key: 'pk_test_xolsnu5dpqpia2a7a8iftygugzyluz2qffkhlid', // Replace with your public key
        reference: 'ORDER_' + Date.now(), // Replace with a unique reference from your system, or remove to let BudPay generate one
        email: 'customer@example.com',
        amount: '1000',
        first_name: 'Ada',
        last_name: 'Okafor',
        currency: 'NGN', // NGN, GHS, KES or USD
        callback_url: '', // Optional. BudPay redirects here after payment, instead of calling the callbacks below
        callback: function (response) {
            // Called when the payment modal closes after a payment attempt
            console.log('Payment complete', response.reference, response.status);
        },
        onClose: function (response) {
            // Called when the customer closes the modal without paying
            console.log('Payment cancelled', response.reference, response.status);
        }
    });
}

Configuration

Important Notes:

1. Find your public key in the BudPay dashboard under Settings > API Credentials. Use pk_test_ keys for testing and pk_live_ keys in production.
2. Generate your own reference for each transaction so you can match payments to orders in your system. It must be unique.
3. Provide either a callback_url or a callback function so you can handle the payment result. If both are set, the customer is redirected to callback_url.
4. The callback function and callback_url only tell you the modal has closed. Always verify the transaction on your server with the reference before giving value to the customer.

2. BudPayCheckoutWithAccessCode

BudPayCheckoutWithAccessCode opens the payment modal for a transaction you have already initialized on your server.

With BudPayCheckout, the full payment payload (amount, currency, customer details, and custom fields) lives in your frontend code, where anyone can inspect or change it before the modal opens. BudPayCheckoutWithAccessCode removes that exposure:

• The payload never reaches the browser. Your server sends the amount, currency, and customer details directly to BudPay using your secret key.
• The payment can't be tampered with. The frontend only holds an access_code and reference, and the modal charges exactly what your server initialized.
• Your server owns the transaction. The reference is issued before the customer pays, so you can record the order and reconcile it against webhooks and verification.

How it works

1. Your server calls the Initialize Transaction API with the payment details and your secret key.
2. BudPay returns an access_code and reference. Your server passes only these two values to the frontend.
3. The frontend calls BudPayCheckoutWithAccessCode to open the payment modal.
4. After the modal closes, your server verifies the transaction using the reference.

Include the library on your checkout page with a script tag:

<script src="https://inlinepay.budpay.com/budpay-inline-custom.js"></script>

Parameters

Obtaining Access Code and Reference

Initialize the transaction from your backend. The request carries the full payment payload and is authenticated with your secret key, so it must never be made from client-side code.

Example cURL Request

Endpoint: POST https://api.budpay.com/api/v2/transaction/initialize

cURLJavascriptPythonGo

More

cURL

More

Try it

1curl -X POST 'https://api.budpay.com/api/v2/transaction/initialize' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "email": "customer@email.com",6  "amount": "20000",7  "callback": "yourcallbackurl"8}'

{  "status": true,  "message": "Authorization URL created",  "data": {    "authorization_url": "https://www.budpay.com/checkout/wp5goiyvc1pt",    "access_code": "wp5goiyvc1pt",    "reference": "REF_61e469c330c2bc"  }}

Powered by

Example Usage

<script src="https://inlinepay.budpay.com/budpay-inline-custom.js"></script>
 
<button onclick="payWithBudPay()">Pay with BudPay</button>

async function payWithBudPay() {
    // Your backend initializes the transaction and returns only access_code and reference
    const response = await fetch("/api/payments/initialize", { method: "POST" });
    const { access_code, reference } = await response.json();
 
    BudPayCheckoutWithAccessCode({
        access_code: access_code,
        reference: reference,
        callback_url: "https://your-callback-url.com", // if callback is not passed, in the API Endpoint, it will redirect to callback_url (if provided), else call the onComplete function
        onComplete: function (data) {
            console.log('Payment completed, Status:', data.status)
            console.log('Payment completed, Reference:', data.reference)
        },
        onCancel: function (data) {
            console.log('Payment cancelled, Status:', data.status)
            console.log('Payment cancelled, Reference:', data.reference)
        },
        debug: true // Show the debug modal to help you pass the right config
    });
}

Important Notes:

1. Do not pass amount, currency, or customer details to BudPayCheckoutWithAccessCode. They are set when you initialize the transaction and cannot be changed from the frontend.
2. The callback names are onComplete and onCancel. The callback and onClose names used by BudPayCheckout do not work with BudPayCheckoutWithAccessCode.
3. If callback_url is provided, the customer is redirected to it and onComplete and onCancel are not called.
4. Callbacks and redirects only tell you the modal has closed. Always verify the transaction on your server with the reference before giving value to the customer.