Developer Tools
React JS

React JS Library

The BudPay React Library lets you accept payments in React applications through a secure payment modal. It provides three integration methods:

MethodHow it worksBest for
BudPayButtonA ready-made button component. The transaction payload is defined in your frontend code.The quickest setup with minimal code.
useBudPayPaymentA hook that opens the modal from your own UI. The transaction payload is defined in your frontend code.Custom buttons and checkout flows.
useBudPayAccessCodeA hook that opens the modal for a transaction initialized on your server. The frontend only receives an access_code and reference.Production checkouts where the amount, currency, or customer details must not be exposed or altered in the browser.

Recommended for production: use useBudPayAccessCode. Anything defined in client-side JavaScript can be read and modified by the customer through the browser's developer tools. Initializing on your server keeps the payment payload out of the browser entirely.

Installation

Install the library with npm:

npm install @budpay/react

1. BudPayButton

BudPayButton is a ready-made button component that opens the payment modal when clicked.

Parameters
ParameterTypeRequiredDescription
api_keystringYesYour BudPay API Key, e.g., "pk_test_1234567890"
amountnumberYesAmount to charge, e.g., 1000
currencystringYesCurrency to charge in, e.g., "NGN"
referencestringNoUnique reference for the transaction, e.g., "BUD_1234567890"
customerobjectYesCustomer details including email, first_name, last_name, and phone.
callback_urlstringNoURL to redirect to after payment, e.g., "https://yourwebsite.com/callback"
onCompletefunctionNoCallback function to execute after payment is successful, e.g., (response) => { console.log(response) }
onCancelfunctionNoCallback function to execute after payment is cancelled, e.g., (response) => { console.log(response) }
custom_fieldsobjectNoCustom fields to include in the transaction, e.g., { custom_field_1: "value1", custom_field_2: "value2" }
debugbooleanNoEnables debug mode, e.g., true
textstringNoThe text to display on the button, e.g., "Pay with BudPay"
classNamestringNoCSS class name for the button styling, e.g., "btn btn-primary"
disabledbooleanNoDisable the button, e.g., false
childrenReactNodeNoContent to be rendered within the button.
Example Usage
import React from 'react';
import { BudPayButton } from '@budpay/react';
 
const config = {
    api_key: "pk_test_1234567890",
    amount: 1000,
    currency: "NGN",
    reference: "BUD_1234567890", // This is auto-generated, if not provided
    customer: {
        email: "johndoe@example.com",
        first_name: "John",
        last_name: "Doe",
        phone: "08012345678"
    },
    callback_url: "https://yourwebsite.com/callback", // If callback_url is not provided, the onComplete function is called (if provided)
    onComplete: (data) => { 
        console.log('Payment completed, Status:', data.status) 
        console.log('Payment completed, Reference:', data.reference) 
    },
    onCancel: (data) => { 
        console.log('Payment cancelled, Status:', data.status) 
        console.log('Payment cancelled, Reference:', data.reference) 
    },
    custom_fields: { custom_field_1: "value1", custom_field_2: "value2" },
    debug: true // Show the debug modal to help you pass the right config
}
 
const buttonConfig = {
    ...config,
    text: "Pay with BudPay",
    className: "btn btn-primary"
}
 
const App = () => (
    <BudPayButton {...buttonConfig} />
);
 
export default App;

2. useBudPayPayment

useBudPayPayment returns a function that opens the payment modal. Call it from any element in your component, such as your own styled button.

Parameters
ParameterTypeRequiredDescription
api_keystringYesYour BudPay API Key, e.g., "pk_test_1234567890"
amountnumberYesAmount to charge, e.g., 1000
currencystringYesCurrency to charge in, e.g., "NGN"
referencestringNoUnique reference for the transaction, e.g., "BUD_1234567890"
customerobjectYesCustomer details including email, first_name, last_name, and phone.
callback_urlstringNoURL to redirect to after payment, e.g., "https://yourwebsite.com/callback"
onCompletefunctionNoCallback function to execute after payment is successful. It receives a response object with reference and status. Example: (response) => { console.log(response) }
onCancelfunctionNoCallback function to execute after payment is cancelled. It receives a response object with reference and status. Example: (response) => { console.log(response) }
custom_fieldsobjectNoCustom fields to include in the transaction, e.g., { custom_field_1: "value1", custom_field_2: "value2" }
debugbooleanNoEnables debug mode, e.g., true
Example Usage
import React from 'react';
import { useBudPayPayment } from '@budpay/react';
 
const App = () => {
    const initiateBudPayPayment = useBudPayPayment({
        api_key: "pk_test_1234567890",
        amount: 1000,
        currency: "NGN",
        reference: "BUD_1234567890", // This is auto-generated, if not provided
        customer: {
            email: "johndoe@example.com",
            first_name: "John",
            last_name: "Doe",
            phone: "08012345678"
        },
        callback_url: "https://yourwebsite.com/callback", // If callback_url is not provided, the onComplete function is called (if provided)
        onComplete: (data) => { 
            console.log('Payment completed, Status:', data.status) 
            console.log('Payment completed, Reference:', data.reference) 
        },
        onCancel: (data) => { 
            console.log('Payment cancelled, Status:', data.status) 
            console.log('Payment cancelled, Reference:', data.reference) 
        },
        custom_fields: { custom_field_1: "value1", custom_field_2: "value2" },
        debug: true // Show the debug modal to help you pass the right config
    });
 
    return (
        <button onClick={initiateBudPayPayment}>Pay with BudPay</button>
    );
};
 
export default App;

3. useBudPayAccessCode

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

With BudPayButton and useBudPayPayment, 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. useBudPayAccessCode 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. Your component calls the function returned by useBudPayAccessCode to open the payment modal.
  4. After the modal closes, your server verifies the transaction using the reference.
Parameters
ParameterTypeRequiredDescription
access_codestringYesYour BudPay access code, obtained from the BudPay API
referencestringYesUnique reference for the transaction, e.g., "BUD_1234567890"
callback_urlstringNoURL to redirect to after payment, e.g., "https://yourwebsite.com/callback"
onCompletefunctionNoCallback function to execute after payment is successful. It receives a response object with reference and status. Example: (response) => { console.log(response) }
onCancelfunctionNoCallback function to execute after payment is cancelled. It receives a response object with reference and status. Example: (response) => { console.log(response) }
debugbooleanNoEnables debug mode, e.g., true
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

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 byXendr
⚠️

Keep your secret key on your server. Return only data.access_code and data.reference to your frontend.

Example Usage
import React from 'react';
import { useBudPayAccessCode } from '@budpay/react';
 
// accessCode and reference are returned by your backend after it initializes the transaction
const Checkout = ({ accessCode, reference }) => {
    const initiatePayment = useBudPayAccessCode({
        access_code: accessCode,
        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: (data) => { 
            console.log('Payment completed, Status:', data.status) 
            console.log('Payment completed, Reference:', data.reference) 
        },
        onCancel: (data) => { 
            console.log('Payment cancelled, Status:', data.status) 
            console.log('Payment cancelled, Reference:', data.reference) 
        },
        debug: true
    });
 
    return (
        <button onClick={initiatePayment}>
            Pay with BudPay
        </button>
    );
};
 
export default Checkout;
Important Notes:
  1. Do not pass amount, currency, or customer details to useBudPayAccessCode. They are set when you initialize the transaction and cannot be changed from the frontend.
  2. If callback_url is provided, the customer is redirected to it and onComplete and onCancel are not called.
  3. 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.

4. closePaymentModal

closePaymentModal closes the payment modal programmatically, if it is open.

Example: Close the Modal After a Timeout

Close the payment modal automatically after 20 seconds:

import React, { useEffect } from 'react';
import { closePaymentModal } from '@budpay/react';
 
const MyComponent = () => {
    useEffect(() => {
        const timer = setTimeout(() => {
            closePaymentModal();
        }, 20000); // 20 seconds
 
        return () => clearTimeout(timer);
    }, []);
 
    return <p>The payment modal will close automatically after 20 seconds.</p>;
};
 
export default MyComponent;
Example: Close the Modal From Callbacks
import React from 'react';
import { useBudPayPayment, closePaymentModal } from '@budpay/react';
 
const MyComponent = () => {
    const initiatePayment = useBudPayPayment({
        api_key: "pk_test_1234567890",
        amount: 1000,
        currency: "NGN",
        customer: {
            email: "johndoe@example.com",
            first_name: "John",
            last_name: "Doe",
            phone: "08012345678"
        },
        onComplete: () => {
            closePaymentModal();
        },
        onCancel: () => {
            closePaymentModal();
        }
    });
 
    return (
        <button onClick={initiatePayment}>
            Pay with BudPay
        </button>
    );
};
 
export default MyComponent;
Vanilla JSReact Native