About the Widget

The Vendy web checkout widget handles payment acceptance in your web application by allowing customers to make payment to merchants using bank transfers or cards. To use, you should have your (public) api key which is found in the business object. Check out Get Businesses to get your business and api key or Create a Business to get started.

How it Works

The Vendy web checkout widget is a lightweight application that embeds an iframe onto a merchant(business) page and allows customers to make payment using bank transfers or cards. the widget has a UI which fills the screen with a light blue overlay with little white "X" at the top right corner of the screen that closes the widget but doesn’t cancel the transaction once it has begun processing and a small responsive modal that displays the processes to be taken till the transaction is completed. The transaction is processed in the following stages:

In the first stage, the transaction request is initiated by Vendy and the details shown to the customer. See Fig 1.1
Next, the customer has to select a payment method depending on what methods are available to the business. See Fig 1.1
For Bank Transfer, Vendy generates 1 or more virtual bank accounts which are tied to the merchant/business account and the customer can then make a bank transfer to the selected account. See Fig 1.2
Once they have made the transfer, they can then click on the "I have made a Transfer" button which then attempts to verify the transaction status and confirm that the transfer has been made to the account specified. See Fig 1.2 and Fig 1.3
Once the transfer is confirmed, then the payment is marked as completed and transaction successful. See Fig 1.4 and 1.5 Else, if the payment is unsuccessful, then the transaction is marked as failed. See Fig 1.6 and 1.7
For Card payment, the customer is presented with a card payment interface which they can then use to enter their card details and authorise the payment. See Fig 2.1 and Fig 2.2
If the authorization is successful, then the Payment is marked as completed and the transaction successful. See Fig 2.3 Else, if the payment is unsuccessful, then the transaction is marked as failed. See Fig 2.4 and 2.5
The widget is automatically closed after 5 seconds of payment completion and the callback function is called depending on the state of the transaction. I.e if the transaction is successful, the OnSuccess function is invoked, else the OnFailure function is invoked.

How to use the widget

Initiating new payment

HTML


Add the script below into the application HTML page.
<script src="https://collections.myvendy.com/v1/inline.min.js" type="text/javascript" charset="utf-8"></script>

Javascript

Create a one time object of VendyPay that can be used to initialise transactions throughout the application.
```
const vendyPay = new VendyPay();
```
Call the "initTransaction" method to initiate a transaction and pop up the widget, It remains on the screen until the transaction is completed. The method requires the following parameters:
1. key - (String) The Public API key for the business. You can get it here
2. amount - (Double) The amount to charge for the transaction, should be above 10
3. currency - (String) The currency of amount for transaction e.g "NGN", "KES". ISO 4217 three-letter code
4. phoneNumber - (String) The phone number of the customer to be billed, it should begin with the country's dial
5. code without the "+" e.g "234709876543"
6. meta - (JSON Object) Object containing any extra information you want recorded with the transaction. Fields
7. within the custom_field object will show up on merchant receipt.
8. onSuccess - (Function) It should take a single Object argument which is the transaction object; it is called after a successful transaction
9. onFailure - (Function) It should take a single Object argument which is the transaction object; It is called if the transaction fails
10. onCancel - (Function) It shouldn’t take any arguments; it is called if the transaction is cancelled while processing the transaction.
11. chargeCustomer - (Boolean, optional) determines if the customer bears the charges/fees for the transaction; defaults to false
12. isTest - (Boolean, optional) determines if this is a test or live transaction; defaults to false (i.e live)

const vendyPay = new VendyPay();
vendyPay.initPayPopup({
    key: 'test_api_ky_xxxxxxxx',
    amount: 100,
    currency: "NGN",
    phoneNumber: "234709876543",
    channel: "whatsapp",
    meta: {
      "email": "test@email.com",
      "custom-key": "custom-value"
    },
    chargeCustomer: true,
    isTest: true,
    onSuccess: (transaction) => {
        /* ... */
    },
    onFailure: (transaction) => {
        /* ... */
    },
    onCancel: _ => {
        /* ... */
    }
});