Drop-in Element

Before you begin

Copy your business public key from the PayChangu dashboard. The public key and a stable form key are all the SDK needs to create or reuse your checkout form.

📘
Use the same formKey whenever you want to show or update the same checkout form.

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

Mount the checkout on your frontend

Choose the layout that fits your page. Each option uses the same public key, form key, customer email, and amount.

<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,
            collect: {
                name: false,
                phone: false,
            },
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

<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,
            collect: {
                name: false,
                phone: false,
            },
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

<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,
            collect: {
                name: false,
                phone: false,
            },
        },
        onSuccess(payment) {
            console.log('Payment successful', payment);
        },
        onError(error) {
            console.error(error.message);
        },
    });
</script>

All configuration options

The complete checkout configuration reference.

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: { // Works on Standard, Accordion, Single
            mobile_money: true, // Works on Standard, Accordion, Single
            card: true, // Works on Standard, Accordion, Single
            bank_transfer: true, // Works on Standard, Accordion, Single
        },

        mobile_money_networks: { // Works on Standard, Accordion, Single
            airtel: true, // Works on Standard, Accordion, Single
            tnm: true, // Works on Standard, Accordion, Single
            changu_wallet: true, // Works on Standard, Accordion, Single
        },

        collect: { // Works on Standard only
            name: false, // Works on Standard only
            phone: false, // Works on Standard only
        },

        appearance: { // Works on Standard, Accordion, Single
            theme: 'light', // Works on all types: light | soft | dark
            brand_color: '#00B9FD', // Works on Standard, Accordion, Single
            radius: 'rounded', // Works on all types: square | rounded | pill
        },

        redirect_url: 'https://merchant.example.com/payment-complete', // Works on all types
    },

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

After the Payment

Four things will happen when a payment is successful:

We’ll redirect you to your callback_url with status tx_ref after payment is complete.
We’ll send you a webhook if you have it enabled. Learn more about webhooks and see examples here.
We’ll send an email receipt to your customer if the payment was successful (unless you’ve disabled this feature).
We’ll send you an email notification (unless you’ve disabled this feature).

On your server, you should handle the redirect and always verify the final state of the transaction.

What if the Payment Fails?

If the payment attempt fails (for instance, due to insufficient funds), you don’t need to take any action. The payment page will remain open, allowing the customer to try again until the payment succeeds or they choose to cancel. Once the customer cancels or after multiple failed attempts, we will redirect to the return_url with the query parameters tx_ref and status of failed.

If you have webhooks enabled, we’ll send you a notification for each failed payment attempt. This can be useful if you want to reach out to customers who experienced issues with their payment. See our webhooks guide for an example.