Drop-in Element

Add a PayChangu checkout form to your checkout page and present one or more payment methods without redirecting customers away first.

Before you begin

Copy your business public key from the PayChangu dashboard.
Choose a stable formKey for this checkout form. Reuse it whenever you need to show or update the same form.
Add the PayChangu checkout SDK to the page that mounts the form:

<script src="https://checkout.paychangu.com/embed.js"></script>

📘
Keep your business public key and formKey consistent for the checkout form you want to reuse.

Mount the checkout

Add an empty element where you want PayChangu to render the checkout.
Call PayChangu.mountCheckoutForm with your public key, form key, customer email, and amount.
Choose a layout below.

Use the accordion layout to let customers expand a payment method as needed.

<div id="paychangu-checkout"></div>

<script src="https://checkout.paychangu.com/embed.js"></script>
<script>
    const checkout = PayChangu.mountCheckoutForm({
        target: '#paychangu-checkout',
        publicKey: 'YOUR_BUSINESS_PUBLIC_KEY',
        formKey: 'checkout-demo',
        email: '[email protected]',
        amount: 5000,
        type: 'accordion',
        config: {
            name: 'Checkout demo',
            currency: 'MWK',
            show_amount: false,
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

On success, the browser console logs Payment successful and the payment object. Errors log the message returned by the checkout.

Use the standard layout to present the configured payment methods in a full checkout form.

<div id="paychangu-checkout"></div>

<script src="https://checkout.paychangu.com/embed.js"></script>
<script>
    const checkout = PayChangu.mountCheckoutForm({
        target: '#paychangu-checkout',
        publicKey: 'YOUR_BUSINESS_PUBLIC_KEY',
        formKey: 'checkout-demo',
        email: '[email protected]',
        amount: 5000,
        type: 'standard',
        config: {
            name: 'Checkout demo',
            currency: 'MWK',
            show_amount: false,
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

Use the single-method layout when you want to show only one method. Set method when type is single.

<div id="paychangu-checkout"></div>

<script src="https://checkout.paychangu.com/embed.js"></script>
<script>
    const checkout = PayChangu.mountCheckoutForm({
        target: '#paychangu-checkout',
        publicKey: 'YOUR_BUSINESS_PUBLIC_KEY',
        formKey: 'checkout-demo',
        email: '[email protected]',
        amount: 5000,
        type: 'single',
        method: 'mobile_money',
        config: {
            name: 'Checkout demo',
            currency: 'MWK',
            show_amount: false,
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

Optional: Configure the checkout

Use the following options to control the checkout shown to your customer. The complete example includes every available option documented for this integration.

Option	Use it to	Availability
`type`	Select `accordion, standard`, or `single`.	All layouts
`method`	Select `mobile_money` for a single-method checkout.	Required for `single`
`methods`	Enable mobile money, card, or bank transfer.	All layouts
`mobile_money_networks`	Enable Airtel, TNM, or Changu Wallet.	All layouts
`collect`	Request the customer's name or phone number.	Standard only
`appearance`	Set the theme, brand color, and corner radius.	All layouts
`redirect_url`	Send customers to a page after the payment flow.	All layouts

const checkout = PayChangu.mountCheckoutForm({
    target: '#paychangu-checkout',
    publicKey: 'YOUR_BUSINESS_PUBLIC_KEY',
    formKey: 'school-fees',
    email: '[email protected]',
    amount: 5000,
    paymentReference: 'ORDER-1001',
    type: 'standard', // standard | accordion | single
    method: 'mobile_money', // Required only when type is single

    config: {
        name: 'School fees', // Works on Standard, Accordion, Single
        currency: 'MWK', // Works on Standard, Accordion, Single
        show_header: true, // Works on Standard only
        title: 'Complete your payment', // Works on Standard only
        description: 'Choose how you would like to pay.', // Works on Standard only
        button_text: 'Continue to payment', // Works on Standard only
        show_amount: true, // Works on Standard only

        methods: {
            mobile_money: true,
            card: true,
            bank_transfer: true,
        },

        mobile_money_networks: {
            airtel: true,
            tnm: true,
            changu_wallet: true,
        },

        collect: {
            name: false,
            phone: false,
        },

        appearance: {
            theme: 'light', // light | soft | dark
            brand_color: '#00B9FD',
            radius: 'rounded', // square | rounded | pill
        },

        redirect_url: 'https://merchant.example.com/payment-complete',
    },

    onReady(form) {
        console.log('Checkout ready', form);
    },
    onSuccess(payment) {
        console.log('Payment successful', payment);
    },
    onError(error) {
        console.error(error.message);
    },
});

Handle the payment result

When a payment succeeds, PayChangu:

Redirects the customer to your redirect_url after the payment completes, including tx_ref and payment status.
Sends a webhook when you have enabled webhooks. See the webhooks reference.
Sends an email receipt to the customer unless you disabled receipts.
Sends you an email notification unless you disabled notifications.

⚠️
Handle the redirect on your server and always verify the final state of the transaction before you fulfill an order or mark a payment as complete.

Handle failed payments

When a payment attempt fails, such as when the customer has insufficient funds, the payment page remains open so the customer can retry or cancel. If they cancel or multiple attempts fail, PayChangu redirects them to redirect_url with tx_ref and a failed status.

If you enabled webhooks, PayChangu sends a notification for each failed attempt. Use these notifications to identify customers who may need help; see the webhooks guide for an example.