This page will help you get started with HeptaPay Payments Plugin.
Introduction
The HeptaPay Plugin allows you to implement HeptaPay checkout services on your website without your customers needing to go to heptapay.com
Getting Started
The HeptaPay HTML/Javscript Plugin works with as follows:
<!DOCTYPE html>
<html>
<head>
<title>HeptaPay Plugin Integration Sample</title>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.4/jquery.min.js"></script>
<script src="https://ap-gateway.mastercard.com/checkout/version/62/checkout.js" data-error="errorCallback" data-cancel="cancelCallback" data-complete="completeCallback"></script>
<script id="hpayPlugin" data-env="dev" data-country="ke" data-phone="0722000000" data-service="Pay" data-account="" data-callback="https://yourwebsite.com/callback" src="https://heptapay.com/static/js/plugin.paypal.hp.js?v=3.8"></script>
</head>
<body>
<div class='heptapaycontainer'>
<input type="number" id="receivedAmount" class="txtAmount" step="1" autoComplete="off" placeholder="KES" value="2000" />
<input type="number" id="sendAmount" class="txtAmount" step=".01" min="1" max="500" autoComplete="off" placeholder="USD" />
<input type="hidden" id="note" value="TrxId" />
<input type="hidden" id="payerEmail" value="" />
<span class="hpayres"></span>
<input id="heptapaybtn" type="button" class='btnPay' value="Pay with HeptaPay" onclick="pay()" />
</div>
</body>
</html>
Let's break this down line by line in the following sections:
JQuery
The HeptaPay plugin relies on JQuery to work. If you already have a version installed on your website, you can use that one. If not, you can use the following public repository:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.4/jquery.min.js"></script>
Mastercard Payment Gateway Services
HeptaPay uses the Masercard Payment Gateway Services (MPGS) gateway to process transactions. The current version that we are using is 62. This line is required.
<script src="https://ap-gateway.mastercard.com/checkout/version/62/checkout.js" data-error="errorCallback" data-cancel="cancelCallback" data-complete="completeCallback"></script>
HeptaPay Plugin Script
The HeptaPay Plugin JavsScript is what HeptaPay uses to run payment services on your website. It is a required parameter. It looks as follows:
<script id="hpayPlugin" data-env="dev" data-country="ke" data-phone="0722000000" data-service="Pay" data-account="" data-callback="https://yourwebsite.com/callback" src="https://heptapay.com/static/js/plugin.paypal.hp.js?v=3.8"></script>
| Parameter | Sample Values | Possible Values |
|---|---|---|
| data-env | dev, prod | The environment that you are using. |
| data-country | rw, ke, ug, bi, cd, us | The country that the recipient phone number is in. |
| data-phone | 0722000000, 254722000000 | The phone number of the recipient of the transaction. For a "Mobile Money" transaction, this is where the payment will be sent to. For a business code transaction, this is where the confirmation SMS will be sent to. Do not include the country code unless the country is set to 'us'. |
| data-service | Pay, MTN MoMo, Airtel Money, Safaricom M-PESA, MoMo Pay, M-PESA Till, MTN Airtime, Airtel Airtime, Econet EcoCash, Merchant | The service that you want your customers to pay to. When set to "Pay", HeptaPay will automatically determine the service for a mobile money transfer. |
| data-account (Optional) | 123456, 1234567 | For use specifically for transactions that require an account number (i.e. M-PESA Till, MoMo Pay). Enter the 6 or 7 digit business till/code. |
| data-callback (Optional) | https://domain.com/callback | The callback URL where HeptaPay should send the the callback of a successful transaction. The parameters are described below. |
| src | https://heptapay.com/static/js/plugin.paypal.hp.js?v=3.8 | The HeptaPay plugin URL and its version. |
Callback Parameters
{"success": 1, "message": "Transaction processed successfully", "hp_trx_id": "HP-091523D768", "ref_trx_id": "TrxId", "trx_local_currency": "KES", "trx_amount": "2000.00"}
{"success": 0, "message": "Transaction failed.", "hp_trx_id": "HP-091523F52D", "ref_trx_id": "TrxId", "trx_local_currency": "KES", "trx_amount": "2000.00"}
HTML Parameters
Received Amount (Required)
This parameter is mandatory. It specifies how much the recipient should receive in local currency after deduction of HeptaPay fees. It can be of type number where the user specifies input, or type hidden.
<input type="number" id="receivedAmount" class="txtAmount" step="1" autoComplete="off" placeholder="KES" value="2000" />
Send Amount (Optional)
This parameter specifies how much the sender will pay inclusive of all HeptaPay fees. It is in USD. If this field is available, the HeptaPay Plugin will automatically convert between the local currency and USD.
<input type="number" id="sendAmount" class="txtAmount" step=".01" min="1" max="500" autoComplete="off" placeholder="USD" />
Transaction Note (Optional)
This parameter is optional. It speficies a note that you may wish to have in the transaction (e.g your own transaction ID). This parameter will be returned in the callback as ref_trx_id
<input type="hidden" id="note" value="TrxId" />
Payer Email (Optional)
This is the email address of the person paying. It can be of type email or hidden where you specify the email address in "value". If entered, the customer will not have to enter their email address again on the card pop-up. If not, the customer will have to enter their email address.
<input type="hidden" id="payerEmail" value="" />
HeptaPay Result (Required)
This parameter will contain the result of a call to the HeptaPay Plugin. It may include helpful error messages and will specify "Transaction Authorized" when the transaction has been accepted for processing.
<span class="hpayres"></span>
HeptaPay Pay Button (Required)
This is the Payment button that the customer must click to initiate a payment. Please note that once clicked, a customer will have to refresh the page for it to work again. Therefore, ensure that you design your website so that the customer only clicks when they are ready to pay. Feel free to change the "value" to anything of your choosing.
<input id="heptapaybtn" type="button" class='btnPay' value="Pay with HeptaPay" onclick="pay()" />