Payment Button

This guide provides instructions on how to integrate the Pay Hero payment button widget into your web application.

Overview

The Pay Hero Payment Button Widget allows merchants and developers to easily integrate a payment button into their websites or applications. The widget provides a seamless way for customers to make payments through Pay Hero without leaving the merchant's site.

Features

• Easy Integration: Just include the JavaScript SDK and configure a few parameters.

• Customizable Button: Set button text, color, and dimensions.

• Event Handling: Listen for successful or failed payments using JavaScript event listeners.

• Redirection Support: Define success and failure URLs for post-payment actions.

• Callback URL Support: Receive a payment payload for backend processing.

Installation

Include the Pay Hero Button SDK in your HTML file:

<script src="https://applet.payherokenya.com/cdn/button_sdk.js?v=3.1"></script>

Usage

To use the widget, insert the following code into your HTML page:

<!-- PayHero Payment Container -->
<div id="payHero"></div>

<script>
    PayHero.init({
        paymentUrl: "https://app.payhero.co.ke/lipwa/5", // Replace with your Lipwa link
        width: "100%",
        height: "100%",
        containerId: "payHero",
        channelID: 100, // Your payment channel ID
        amount: 1, // Payment amount
        phone: "0712345678", // (Optional) Customer phone
        name: "Good Samaritan", // (Optional) Customer name
        reference: "buttonTesting", // (Optional) Payment reference
        buttonName: "Pay Now KES 1", // Button text
        buttonColor: "#00a884", // Button color
        successUrl: null, // (Optional) Redirect URL after success
        failedUrl: null, // (Optional) Redirect URL after failure
        callbackUrl: null // (Optional) Webhook URL to receive payment payload
    });

    // Handling payment success or failure
    window.addEventListener('message', function(event) {
        if (event.data.paymentSuccess) {
            console.log("Payment Successful:", event.data);
            alert('Payment successful!');
        } else {
            alert('Oopsie! Payment failed');
        }
    });
</script>

Parameters

Parameter	Required	Description
paymentUrl	Yes	Your Pay Hero Lipwa payment link.
width	No	Width of the button (default: 100%).
height	No	Height of the button (default: 100%).
containerId	Yes	The HTML element ID where the button will be injected.
channelID	Yes	Your unique payment channel ID.
amount	Yes	The amount to be paid.
phone	No	Customer's phone number (optional).
name	No	Customer's name (optional).
reference	No	A unique reference for tracking payments.
buttonName	Yes	The text displayed on the payment button.
buttonColor	Yes	The color of the payment button.
successUrl	No	URL to redirect the user upon a successful payment.
failedUrl	No	URL to redirect the user if the payment fails.
callbackUrl	No	Webhook URL where Pay Hero sends the payment details upon success.

Handling Payment Events

To listen for payment success or failure, use the following JavaScript event listener:

window.addEventListener('message', function(event) {
    if (event.data.paymentSuccess) {
        console.log("Payment Details:", event.data);
    } else {
        console.error("Payment failed");
    }
});

Use Cases

1. E-commerce Websites: Enable customers to make instant payments for products or services.

2. Service Providers: Freelancers or businesses can embed the button for easy payment collection.

3. Event Ticketing: Sell event tickets online with a seamless checkout experience.

4. Donations: Non-profits can collect donations with a single click.

5. Subscription Payments: Collect recurring or one-time subscription fees from users.

Conclusion

The Pay Hero Payment Button Widget simplifies payment processing, making it easier for businesses and individuals to collect payments securely. With a few lines of code, you can integrate a fully functional payment button into your website.

Success Callback URL Payload

This is the payload that will be sent to the provided callback URL via POST.

{
  "paymentSuccess": true,
  "reference": "c632-4e27-9718-f9fcdec511d826234",
  "user_reference": "buttonTesting",
  "provider": "m-pesa",
  "providerReference": "TCT3K99UFZ",
  "amount": 1,
  "phone": "0708344101",
  "customerName": "Good Samaritan",
  "channel": "100"
}

DEMO

https://applet.payherokenya.com/deposit/button.html

Support

If you encounter any issues or have questions, please contact Pay Hero support at [e-mail].

Credits: Wahome Mutahi