Congratulations! You just found the easiest way to integrate with the BENEFIT payment system in Bahrain!
BenefitJSยน is a simple, open-source library that allows you to accept BENEFIT payments through a modern, reliable interface that is optimized around the User Experience.
It was born out of a frustration with the verbose, cryptic and unappealing integration process that comes standard with BENEFIT integrations.
BenefitJS provides:
- ๐ฑ A stunning mobile-first user experience that massively improves upon the default Benefit integration
- ๐ Same-page checkout (finally!) using a sleek, modern modal dialog
- ๐ Additional features, including support for one-click checkout (or "Tokenization", in payments lingo)
- ๐ง Premium support, available to Enterprise customers (more below)
This is what the default (and rather distasteful) Benefit integration looks like:
.. and here's what the BenefitJS checkout page looks like:
This project consists of two main parts:
- An
index.js
that creates an<iframe>
in the parent window, or opens a separate window on mobile devices. - Checkout, a Vue application with the actual Checkout form, is added as a submodule at
inner/
.
Since the two projects are tightly coupled, we track them jointly through this repository.
To integrate using Benefit.js, you'll need an account with BENEFIT. If you don't already have one, sign up for a BENEFIT account through Credimax
Assuming you have an account, you can now:
- Register for a BenefitJS account at https://benefitjs.com
- Upload your
resource.cgn
file to the Dashboard, and receive your public key. - Integrate BenefitJS into your website using the sample code below:
<form action="/pay" method="POST">
<script
src="//fast.benefitjs.com"
data-key="key_..."
data-transaction-id="19201"
data-amount="12.345"
></script>
<!-- loads 'Pay' button, submits <form> when done -->
</form>
Interested in more finer-grained control of the checkout? Then custom mode is for you!
const benefitHandler = new BenefitJS({ key: 'key_...', transactionId: 'Order 12910', amount: 1.234, // BHD onClose: () => { console.warn('onClose() called') }, onCancel: () => { console.warn('onCancel() called') }, onComplete: () => { console.info('onComplete() called') } })
For a complete list of data-
params, see the Supported options section below.
- Create a
.env.development
file with the following keys:CHECKOUT_URL=http://localhost:8080
, or whatever the local server URL is for yourinner
repositoryDEBUG_MODE=true
, to enable debug messages in the browser console
- Run
yarn run serve
This should open up the demo.html
file in your browser. Editing the index.js
script should automagically reload your browser and keep things in sync!
To update to the latest version of inner
, simply run git submodule update --remote
from the inner/
directory.
The wrapper index.js
script is deployed to https://fast.benefitjs.com/benefit.js
, our global static CDN-hosted endpoint.
Checkout is deployed at a separate endpoint at https://checkout.benefitjs.com/
.
Enterprise users are welcome to contact us at sales@benefitjs.com for priority support plans for your organization. All other users may open an issue on this repository.
Below is a comprehensive list of the common options supported by the BenefitJS library for both integration types (simple and custom):
Key | Required? | Description | Sample |
---|---|---|---|
key / data-key |
Required | The public key that uniquely identifies you as a seller. You can get this key from the BenefitJS dashboard | 89b51c9e-9338-11e9-9cc3-0242ac110003 |
transactionId / data-transaction-id |
Required | Any unique character sequence that can be used to identify this order. Usually something your backend generates | Order-1234 |
amount / data-amount |
Required | The amount that the customer will pay for the order, in BHD. This is a decimal value | 1.234 = BHD 1.234 |
title / data-title |
Optional | The title shown on top of the payment page. Great place to put the seller name | Batelco . Default is Pay with BENEFIT |
subtitle / data-subtitle |
Optional | Displayed directly under the title on the payment page. Great place to include a description of the items being purchased. | Bill payment for 3999 9999 . Default is `` (empty) |
The options below are only supported by the Simple integration:
Option | Required? | Description |
---|---|---|
data-button-text |
optional | The text shown on the "Pay Now" button that is generated. Defaults to Pay by Debit Card |
The Custom integration supports the following callbacks:
Option | Required? | Description |
---|---|---|
onCancel |
optional | Function that is called when the payment dialog is cancelled by the user. |
onComplete |
optional | Function that is called when the payment is successfully completed. |
onClose |
optional | The function that is called when the modal dialog is closed. This is always triggered on modal close, regardless of the underlying reason (e.g. user cancellation or payment completion). |
ยน Note: BenefitJS is not affiliated with The BENEFIT Company in Bahrain. This open source library is provided by contributors to help improve the payment experience for customers and companies in Bahrain.
If you would like to contribute to this project, please review the CONTRIBUTING guidelines.