PAY HERO DOCS
  • Introduction-Pay Hero Developer APIs
  • Creating Account
  • Authorization
  • GET: Service Wallet Balance
  • GET: Payments Wallet Balance
  • POST: Service Wallet Top Up
  • POST: Initiate MPESA STK Push Request
  • Payment Button
  • Lipwa Link
  • POST: Pay Hero Wallet- Withdraw To Mobile
  • GET: Account Transactions
  • GET: Transaction Status
  • WooCommerce Plugin
    • Plugin Installation
  • Shopify
  • Videos
  • Other Integrations
  • Email API Reference
    • Register SMTP
    • Send Email
    • Mail status
  • WhatsApp API Reference
    • Introduction
    • Getting Started
    • Send API Whats App Text
    • Bulk WhatsApp API Messaging
    • Bulk WhatsApp Using UI/CSV File
Powered by GitBook
On this page
  • Overview
  • Features
  • Installation
  • Usage
  • Parameters
  • Handling Payment Events
  • Use Cases
  • Conclusion
  • Success Callback URL Payload
  • DEMO
  • Support

Was this helpful?

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

Support

Credits: Wahome Mutahi

PreviousPOST: Initiate MPESA STK Push RequestNextLipwa Link

Last updated 1 month ago

Was this helpful?

If you encounter any issues or have questions, please contact Pay Hero support at .

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