@paystack/checkout-js 1.32.0 → 1.33.0-dev.1

package/README.md

@@ -4,54 +4,1349 @@ This is the client-side JS library for billing customers with Paystack. It makes
 
 It is used in Checkout, Paystack's proprietary checkout form.
 
-# Documentation
+# Installation
 
-See the [Checkout JS public docs](./PUBLIC_DOCS.md) and [development docs](./DEV_DOCS.md)
+```bash
+npm install @paystack/checkout-js --save
+```
 
-# Installation
+or just grab the js file and add it to your html directly
+
+```html
+<script src="https://js.paystack.co/v1/checkout.js"></script>
+```
+
+# Quick Start
+
+## Usage via NPM/Yarn
+
+```js
+import { Transaction } from 'checkout-js';
+
+async function chargeCustomerCard() {
+  const transactionData = {
+    email: 'test@paystack.com', // replace this with customer email
+    amount: 100,
+    key: 'your_paystack_public_key',
+  };
+  
+  try {
+    const transaction = await Transaction.request(transactionData);
+    await transaction.setCard({
+      number: '4084084084084081',
+      cvv: '408',
+      month: '01',
+      year: '20',
+      pin: '1234',
+    });
+    // charge resolves to a ChargeResponse
+    const chargeResponse = await transaction.chargeCard();
+    if (chargeResponse.status === 'success') {
+      console.log('card was charged successfully!');
+    }
+  } catch (error) {
+    console.log(error);
+  }
+}
+
+chargeCustomerCard();
+```
+
+## Usage via inline script
+
+Add the Checkout JS script to your `HTML` document
+
+```html
+<script src="https://js.paystack.co/v1/checkout.js"></script>
+```
+
+And then access the available classes in your JavaScript file;
+
+```js
+var transactionData = {
+  email: 'test@paystack.com', // replace this with customer email
+  amount: 100,
+  key: 'your_paystack_public_key',
+};
+
+var customerCardDetails = {
+  number: '4084084084084081',
+  cvv: '408',
+  month: '01',
+  year: '20',
+  pin: '1234',
+};
+
+function chargeCustomerCard() { 
+  Transaction.request(transactionData).then(function(createdTransaction) {
+    createdTransaction.setCard(customerCardDetails);
+    return createdTransaction.chargeCard();
+  }).then(function(chargeResponse) {
+    if (chargeResponse.status === 'success') {
+      console.log('card was charged successfully!');
+    }
+  }).catch(function(error) {
+    console.log(error);
+  });
+}
+
+chargeCustomerCard();
+```
+
+# Getting Started
+
+These are the classes exported by `checkout js`:
+
+1. **Transaction**
+2. **Toolkit**
+3. **Card**
+4. **BankAccount**
+
+The `Transaction` class is the most important class in Checkout JS. All the functions required for initializing a transaction, updating it, and charging a customer using the supported payment channels are bound to this class.
+
+For example, charging a customer's card could entail the following steps;
+
+1. Request a new transaction
+2. Collect and validate card details from customer
+3. Save the card to the transaction
+4. Charge the card
+5. Tada!
+
+## Table of contents
+
+This is a grouping of the methods exported by the `Transaction` class:
+
+- Initializing a transaction
+    - `Transaction.request`
+    - `Transaction.requestWithAccessCode`
+    - `Transaction.validate`
+- Charging a card
+    - `Transaction.setCard`
+    - `Transaction.chargeCard`
+    - `Transaction.authenticateCard`
+    - `Transaction.listenFor3DSCharge`
+- Charging a Bank account
+    - `Transaction.setBankAccount`
+    - `Transaction.chargeBankAccount`
+    - `Transaction.registerBankAccount`
+    - `Transaction.authenticateBankAccount`
+    - `Transaction.getIbankUrl`
+    - `Transaction.listenForIbankCharge`
+    - `Transaction.chargeDigitalBankMandate`
+    - `Transaction.listenForDigitalBankMandateCharge`
+- Charging via USSD
+    - `Transaction.getUSSDShortcode`
+    - `Transaction.listenForUSSDCharge`
+- Charging via QR
+    - `Transaction.getQRCode`
+    - `Transaction.listenForQRCharge`
+- Charging via Mobile Money (Only available for GHS transactions)
+    - `Transaction.chargeMobileMoney`
+    - `Transaction.listenForMobileMoneyCharge`
+- Transaction analytics
+    - `Transaction.initializeLog`
+    - `Transaction.getTimeSpent`
+    - `Transaction.logPageOpen`
+    - `Transaction.logChannelSwitch`
+    - `Transaction.logPageClose`
+    - `Transaction.logInput`
+    - `Transaction.logValidationErrors`
+    - `Transaction.logAuthWindowOpen`
+    - `Transaction.logAuthWindowClose`
+    - `Transaction.logAPIResponse`
+    - `Transaction.logAttempt`
+    - `Transaction.saveReferrer`
+- Check transaction status
+    - `Transaction.requery`
+
+Utility classes:
+
+- Toolkit: This contains utilities that you can use during a transaction
+    - Toolkit.contents
+    - Toolkit.fetch
+- Card: Use this to validate your customer’s cards
+    - Card.validate
+    - Card.isNumberValid
+    - Card.getType
+    - Card.isCvvValid
+    - Card.isExpiryValid
+- BankAccount: Use this to validate your customer’s bank accounts
+    - BankAccount.validate
+    - BankAccount.isValidNubanAccount
+
+## # Initializing a transaction
+
+## Transaction.request(transactionData)
+
+This method returns a new transaction instance. The instance returned is what is used to complete the customer’s payment. 
+
+Base parameters for this method are:
+
+| Parameter                     | Required      | Type                | Description                                          |
+| ----------------------------- | --------------| --------------------| ---------------------------------------------------- |
+| email                         | True          | `String`            | The customer's email address                         |
+| amount                        | True          | `String` | `Number` | Amount in smallest currency unit (kobo/pesewa/cents). Ignored if creating a subscription            |
+| key                           | True          | `String`            | Your Paystack public key. You can find this on your dashboard in Settings > API Keys & Webhooks     |
+| reference                     | False         | `String`            | Unique case sensitive transaction reference. Only `-`,`.`, `=` and alphanumeric characters allowed  |
+| channels                      | False         | `Array`             | An array of payment channels to use. Defaults to all available channels on an integration  |
+| currency                      | False         | `String`            | The currency of the transaction. Default is `NGN`
+| amount                        | True          | `String`            | Amount in smallest currency unit (kobo/pesewa/cents). Ignored if creating a subscription            |
+| firstName                     | False         | `String`            | The first name of the customer                                                                      |
+| lastName                      | False         | `String`            | The last name of the customer  |
+| phone                         | False         | `String`            | The phone number of the customer  |
+| metadata                      | False         | `Object`            | A valid object of extra information that you want to be saved to the transaction.  |
+| cusotmer_code                 | False         | `String`            | The customer code for the customer on Paystack  |
+
+
+Other optional parameters for [Split Payments](https://paystack.com/docs/payments/split-payments/) and [Recurring Charges](https://paystack.com/docs/payments/recurring-charges/)
+
+| Parameter                     | Required      | Type                | Description                                          |
+| ----------------------------- | --------------| --------------------| ---------------------------------------------------- |
+| plan                          | False         | `String`            | If transaction is to create a subscription to a predefined plan, provide plan code here                         |
+| subaccountCode                | False         | `String`            | A valid Paystack subaccount code e.g. `ACCT_8f4s1eq7ml6rlzj`    |
+| split_code                    | False         | `String`            | A valid Paystack split code e.g. `SPL_qQsdYLXddd`    |
+| bearer                        | False         | `Number`            | Who bears Paystack charges? `account` or `subaccount` (defaults to `account`).                |
+| transactionCharge             | False         | `String`            | A flat fee (in kobo) to charge the subaccount for this transaction. This overrides the split percentage set when the subaccount was created.    |
+| planInterval                  | False         | `String`            | Interval for the plan. Valid intervals are `hourly`, `daily`, `weekly`, `monthly`, `annually` |
+| subscriptionStartDate         | False         | `String`            | The start date for the subscription (after the first charge)                        |
+| planCode                      | False         | `String`            | A valid Paystack plan code e.g. `PLN_cujsmvoyq2209ws`  |
+| subscriptionCount             | False         | `Number`            | The number of subscriptions to create for this plan     |
+| subscriptionLimit             | False         | `Number`            | The number of times to charge for this subscription                                 |
+
+
+**Example**
+
+```ts
+import { Transaction } from 'checkout-js';
+
+interface Parameters {
+	key: string;
+  email: string;
+	amount: number;
+  ref?: string;
+  customer_code?: string;
+  plan?: string;
+  transaction_charge?: string;
+  bearer?: string;
+  channels?: string[];
+  currency?: string;
+  firstname?: string;
+  lastname?: string;
+  phone?: string;
+  remark?: string;
+  payment_page?: string;
+  payment_request?: string;
+  quantity?: string;
+  coupon?: string;
+  start_date?: string;
+  interval?: string;
+  invoice_limit?: number;
+  subaccount?: string;
+  hash?: string;
+  metadata?: string;
+}
+  
+const transactionData: Parameters = {
+  email: 'test@paystack.com', // replace this with the customer's email
+  amount: 100,
+  key: 'your_paystack_public_key',
+};
+  
+// returns an instance of the Transaction class
+const transaction = await Transaction.request(transactionData);
+```
+
+## Transaction.requestWithAccessCode(accessCode)
+
+While the `Transaction.request` method lets you create transactions from scratch in the browser, `Transaction.requestWithAccessCode` lets you complete a transaction [initialized from your server](https://paystack.com/docs/api/#transaction-initialize) on the frontend. This method can be more secure and it, ensures no new transactions are created on the frontend.
+
+**Example**
+
+```js
+import { Transaction } from 'checkout-js';
+
+const accessCode = 'ltxo947mrhrbz6z'; // Access code for transaction created on your server using the Paystack API
+
+// returns an instance of the transaction class
+const transaction = await Transaction.requestWithAccessCode(accessCode);
+```
+
+## Transaction.validate(transaction)
+
+This is a utility method used to validate the parameters for requesting a new transaction.
+
+**Example**
+
+```js
+import { Transaction } from 'checkout-js';
+  
+const transactionData = {
+  email: 'test@paystack.com', // replace this with the customer's email
+  amount: 100,
+  key: 'your_paystack_public_key',
+};
+
+try {
+  Transaction.validate(transactionData); // throws validation errors
+} catch (error) {
+  // handle validation errors thrown by Transaction.validate
+}
+```
+
+NB: `Transaction.request` calls this validation function implicitly, so you do not need to call it yourself except if you need to handle parameter validation separately.
+
+## Attempting a Charge
+
+For each attempt to charge a payment instrument, `checkout-js` responds with a `ChargeResponse`. This `ChargeResponse` has the following interface depending on the kind of response received:
+
+```ts
+interface ChargeResponse {
+  status: string;
+  message: string;
+  data?: Object
+  errors?: Array;
+}
+```
+reference will be made to this `ChargeResponse` throughout the rest of the documentation. More details [here](#charge-responses)
+
+## # Charging a card
+
+Charging a card includes the following steps:
+
+1. Set the card on the transaction
+2. Charge the card
+3. If required, authenticate the charge
+
+## transaction.setCard({ number, cvv, month, year, pin })
+
+This is an instance method on transactions to set a card to be charged for the transaction. With this, you can
+
+**Example**
+
+```js
+import { Transaction } from 'checkout-js';
+
+const transactionData = { ... };
+const transaction = await Transaction.request(transactionData)
+
+interface Card {
+	number: string;
+	cvv: string;
+	month: string;
+	year: string;
+}
+
+/**
+ * Card number can have varying lengths, typically from 16 to 19 characters
+ * CVV can be 3 or 4 characters in length
+ */
+
+const newCard = {
+  number: '4084084084084081',
+  cvv: '408',
+  month: '01',
+  year: '20'
+}
+
+await transaction.setCard(newCard);
+```
+
+## transaction.chargeCard()
+
+After setting a card on a transaction, you can now attempt to charge it by calling `chargeCard()`
+
+**Example**
+
+```jsx
+import { Transaction } from 'checkout-js';
+...
+const chargeResponse = await transaction.chargeCard();
+```
+## transaction.authenticateCard(phoneOrOtp)
+
+If `chargeResponse` returns a response with `status ===` `'auth'` you can request the customer's phone number or the OTP sent to their phone number. `data.auth` on the `chargeResponse` states what type of authentication is required.
+
+**Example**
+
+```js
+import { Transaction } from 'checkout-js';
+
+const newCard = {
+  number: '4084084084084081',
+  cvv: '408',
+  month: '01',
+  year: '20'
+}
+
+await transaction.setCard(newCard);
+
+...
+
+let chargeResponse = await transaction.chargeCard();
+
+if (chargeResponse.status === 'auth') {
+  let authResponse;
+  if (chargeResponse.data.auth === 'pin') {
+    // request customers phone number
+    newCard.pin = '1234'
+		await transaction.setCard(newCard)
+		chargeResponse = await transaction.chargeChard(); // attempt to charge the card again with the pin included
+  } 
+if (chargeResponse.data.auth === 'otp') {
+    // request otp sent to customer
+    const otp = '123456';
+    authResponse = await transaction.authenticateCard(otp); // returns a ChargeResponse
+  }
+}
+```
+
+## transaction.listenFor3DSCharge(callback)
+
+Use this function to wait for the response from the 3DS authentication from the customer. You’d need this if the charge response returns an auth type of `3ds`:
+
+```js
+const chargeResponse = {
+  status: 'auth',
+  message: 'url-for-3ds-authentication',
+  data: {
+    auth: '3ds',
+  },
+}
+```
+
+The callback function will be called with the response and a function to unsubscribe from pusher.
+
+**Example**
+
+```js
+const chargeResponse = await transaction.chargeCard();
+...
+function handleResponse(response, unsubscribe) {}
+
+if (chargeResponse.status === 'auth') {
+  if (chargeResponse.data.auth === '3DS') {
+    // redirect customer to 3ds url in `chargeResponse.message`
+    // listen for response from 3ds authentication
+    listenFor3DSCharge(handleResponse); 
+  }
+}
+```
+
+## # Charging a bank account
+
+To charge a bank account, you need to make sure it’s from one of the banks that Paystack supports bank payments from. To get a list of supported banks, call `Toolkit.fetch('banks')`.
+
+```js
+import { Toolkit } from 'checkout-js';
+
+const banks = await Toolkit.fetch('banks'); 
+
+// This will return an array of available banks like;
+[
+  {
+    "name": "Access Bank",
+    "slug": "access-bank",
+    "code": "044",
+    "longcode": "044150149",
+    "gateway": "emandate",
+    "pay_with_bank": true,
+    "active": true,
+    "is_deleted": null,
+    "country": "Nigeria",
+    "currency": "NGN",
+    "type": "nuban",
+    "id": 1,
+    "createdAt": "2016-07-14T10:04:29.000Z",
+    "updatedAt": "2016-07-14T10:04:29.000Z"
+  },
+  {
+    "name": "Guaranty Trust Bank",
+    "slug": "guaranty-trust-bank",
+    "code": "058",
+    "longcode": "058152036",
+    "gateway": "ibank",
+    "pay_with_bank": true,
+    "active": true,
+    "is_deleted": null,
+    "country": "Nigeria",
+    "currency": "NGN",
+    "type": "nuban",
+    "id": 9,
+    "createdAt": "2016-07-14T10:04:29.000Z",
+    "updatedAt": "2016-07-14T10:04:29.000Z"
+  },
+  ...
+]
+```
+`checkout-js` currently handles three kinds of bank payments determined by the `gateway` on the bank object. The gateways are `emandate`, `ibank` and `digitalbankmandate`.
+
+- `emandate` payments follow a “registration → verification → authentication” payment flow.
+- `ibank` payments require that your customers be redirected to their internet banking portal for authentication, after which they will be redirected back to your payment flow.
+- `digitalbankmandate` payments need to be authenticated with a phone number and a `payId`
+
+Most banks use the `emandate` flow while Guaranty Trust Bank and First Bank use the `ibank` flow and Kuda Bank uses the `digitalbankmandate` flow. 
+
+## # Ibank Flow
+
+## transaction.getIbankUrl(bank)
+
+This method is used to fetch the internet banking url through which a customer can complete a transaction.
+
+**Example**
+
+```js
+...
+
+const bank = {
+  ...
+  bankId: 9,
+  name: 'Guaranty Trust Bank',
+  gateway: 'ibank',
+  ...
+};
+
+await transaction.getIbankUrl(bank);
+```
+
+## transaction.listenForIbankCharge(callback)
+
+When the customer has been redirected to their internet banking portal to complete the transaction, you can wait for the final result using this function, passing a callback that will be called with the response and a function to unsubscribe from `pusher`.
+
+**Example**
+
+```js
+...
+// fetch internet banking URL
+const url = await transaction.getIbankUrl(bank);
+
+// redirect customer to internet banking portal
+...
+// listen for response from internet banking portal
+function handleResponse(response, unsubscribe) {}
+
+transaction.listenForIbankCharge(handleResponse); 
+// resolves to ChargeResponse
+```
+
+## # DigitalBankMandate Flow (Kuda Bank)
+
+## transaction.chargeDigitalBankMandate({ phoneNumber, payId, bankId })
+
+This function makes an attempt to charge a kuda bank account using the customer's phone number and a 6-digit `payID` which the customer will generate from their kuda bank app
+
+**Example**
+
+```js
+...
+
+const bank = {
+  ...
+  id: 67,
+  name: 'Kuda Bank',
+  gateway: 'digitalbankmandate',
+  ...
+};
+const phoneNumber = '07033773883'
+const payId = 288299;
+const params = {
+   phoneNumber,
+	 bankId: bank.id,
+   payId
+}
+
+// resolves to ChargeResponse
+await transaction.chargeDigitalBankMandate(params);
+```
+
+## transaction.listenForDigitalBankMandateCharge(callback, pusherChannel)
+
+After calling the `chargeDigitalBankMandate` function, you need to call the `listenForDigitalBankMandateCharge` function to be notified of the status of the payment. This function accepts a `callback` which will be called with the response as well as a function to unsubscribe from pusher — and a `pusher_channel`, a property on `data` gotten from the response to `chargeDigitalBankMandate`.
+
+```js
+const {
+	status,
+	message,
+	data
+} = await transaction.chargeDigitalBankMandate(params);
+
+function handleResponse(response, unsubscribe) {}
+
+transaction.listenForDigitalBankMandateCharge(handleResponse, data.pusher_channel)
+```
+
+## # Emandate flow
+
+## transaction.setBankAccount({ bankId, accountType, accountNumber })
+
+Sets the bank account the customer is going to use to complete the transaction.
+
+**Example**
+
+```js
+import { Transaction, Toolkit } from 'checkout-js';
+...
+ const bank = {
+  ...
+  id: 1,
+  name: 'Access Bank',
+  gateway: 'emandate',
+  type: 'nuban',
+  ...
+};
+
+const bankAccount = {
+  bankId: bank.id,
+  accountType: bank.type,
+  accountNumber: '1234567890', // customer account number
+}
+
+await transaction.setBankAccount(bankAccount);
+```
+
+## transaction.chargeBankAccount()
+
+This method is responsible for charging the bank account that has been set on the transaction using `transaction.setBankAccount()`.
+
+**Example**
+
+```js
+const chargeResponse = await transaction.chargeBankAccount();
+// resolves to a ChargeResponse
+```
+
+## transaction.registerBankAccount(birthday)
+
+Use this to register new customer bank accounts for e-mandate so they can be charged. You should do this if you get a response requiring birthday registration after attempting to charge a bank account with `transaction.chargeBankAccount`.
+
+```js
+{
+  status: 'auth',
+  message: 'This customer needs to register their account',
+  data: {
+    auth: 'birthday'
+  }
+}
+```
+
+**Example**
+
+```jsx
+...
+await transaction.setbankAccount({...});
+
+const chargeResponse = await transaction.chargeBankAccount();
+
+if (chargeResponse.status === 'auth' && chargeResponse.data.auth === 'birthday') {
+  // pass the customer's birthday in the format 'dd-MM-yyyy'
+  const authResponse = await transaction.registerBankAccount('12-05-1980');
+  // resolves to a ChargeResponse
+}
+```
+
+## transaction.authenticateBankAccount(otp)
+
+This method is used to authenticate bank transactions using an `otp`.
+
+**Example**
+
+```jsx
+...
+await transaction.setbankAccount({...});
+const chargeResponse = await transaction.chargeBankAccount();
+
+if (chargeResponse.status === 'auth' && chargeResponse.data.auth === 'otp') {
+  const authResponse = await transaction.authenticateBankAccount(123456);
+  // resolves to a ChargeResponse
+}
+```
+
+## # Charging via USSD
+
+The only available USSD channels for now are GTB’s 737, Sterling's 822, Zenith's 966 and UBA's 919
+
+## transaction.getUSSDShortcode({ channel })
+
+Use this to generate a USSD shortcode
+
+**Example**
+
+```jsx
+// initialize transaction
+const response = await transaction.getUSSDShortcode({ channel: '919' });
+
+// returns a response in the format
+{
+  "status": true,
+  "message": "Offline Reference Generated Successfully",
+  "data": {
+    "reference": "887462",
+    "channel": "api_919_shortcode_00000",
+    "code": "*919*00*1*0000#"
+  }
+}
+```
+
+Present the code in `data.code` to your customers for payment. 
+
+## transaction.listenForUSSDCharge({ channel }, callback)
+
+Listen for when the customer completes the transaction via USSD. This function accepts a callback function to be called with the response and a function to unsubscribe from pusher.
+
+**Example**
+
+```js
+// initialize transaction
+...
+function handleResponse(response, unsubscribe) {}
+
+transaction.listenForUSSDCharge({ channel: '919' }, handleResponse);
+
+// return a ChargeResponse
+```
+
+## # Charging via QR
+
+The available QR channels are `visa` in Nigeria and `MPASS_OLTI` in South Africa .
+
+## transaction.getQRCode({ channel })
+
+Use this to generate a QR code
+
+**Example**
+
+```js
+// initialize transaction
+const response = await transaction.getQRCode({ channel: 'visa' });
+
+// returns a response in the format
+{
+  "status": true,
+  "message": "QR successfully generated",
+  "data": {
+    "errors": false,
+    "url": "qr code image",
+    "qr_code": "qr code",
+    "status": "success",
+    "channel": "qr channel"
+  }
+}
+```
+Display the QR code image in `data.url` for your customers to scan. 
+
+
+## transaction.listenForQRCharge({ channel }, callback)
+
+Listen for when the customer has completed the transaction by scanning the QR code. This function accepts an object containing the QR `channel` and a callback function to be called with the response and a function to unsubscribe from pusher.
+
+**Example**
+
+```js
+// initialize transaction
+...
+function handleResponse(response, unsubscribe) {}
+
+transaction.listenForQRCharge({ channel: 'visa' }, handleResponse);
+
+// return a ChargeResponse
+```
+
+## # Charging a mobile money wallet
+
+## transaction.chargeMobileMoney({ phoneNumber, provider, voucher?, registrationToken? })
+
+This function is used to attempt a mobile money charge with a `phoneNumber`, a `provider` and optionally, a `voucher` and a `registrationToken`
+
+**Available providers**
+
+```js
+[
+   { name: 'MTN', value: 'MTN', prefix: ['+23354', '+23355', '+23324'] },
+   { name: 'TGO', 
+     value: 'Airtel/Tigo', 
+     prefix: ['+23327', '+23357', '+23326', '+23356'] 
+   },
+   { name: 'VOD', value: 'Vodafone', prefix: ['+23320', '+23350'] },
+]
+```
+
+**Example**
+
+```js
+// initialize transaction
+...
+const response = await transaction.chargeMobileMoney(
+  { phoneNumber: '05012345678', provider: 'VOD' }
+);
+
+// returns a response in the format
+{
+  "status": true,
+  "message": "Charge attempted",
+  "data": {
+    "transaction": 2,
+    "phone": "05012345678",
+    "device": "96640369ca64b60d3dcf",
+    "provider": "VOD",
+    "channel_name": "MOBILE_MONEY_2",
+    "display": {
+      "type": "voucher",
+      "message": "Please enter your voucher code to complete this payment"
+    }
+  }
+}
+
+/**
+* Depending on what the `display.type` is from the previous response, you might
+* need to collect additional information to complete the payment
+*/
+
+/**
+* If you get a `display.type === voucher`, collect a voucher from the customer
+* and call chargeMobileMoney again, this time including the voucher as one of the
+* arguments
+*/
+const response = await transaction.chargeMobileMoney(
+  { 
+    phoneNumber: '05012345678', 
+    provider: 'VOD', 
+    voucher: 'voucher-code' 
+  }
+);
+
+/**
+* If you get a `display.type === registration_token`, collect a registrationToken from the customer
+* and call chargeMobileMoney again, this time including the registrationToken
+* as one of the arguments
+*/
+const response = await transaction.chargeMobileMoney(
+  { 
+    phoneNumber: '05012345678', 
+    provider: 'VOD', 
+    registrationToken: 'token' 
+  }
+);
+ 
+/**
+* The `registrationToken` phase should be the last stage in the process after 
+* which you should start listening for a response as stated in the next section
+*/
+
+```
+
+## transaction.listenForMobileMoneyCharge(callback)
+
+Listen for when the customer has completed the payment, passing a callback function to be called with the response and a function to unsubscribe from pusher.
+
+**Example**
+
+```js
+// initialize transaction
+...
+function handleResponse(response, unsubscribe) {}
+
+transaction.listenForQRCharge(handleResponse);
+
+// return a ChargeResponse
+```
+
+## # Transaction Analytics
+
+These are a group of functions that help to populate the transaction timeline which is attached to every transaction and can be viewed on the Paystack dashboard.
+
+Checkout JS implicitly handles some analytics like logging inputs, bank selection, errors, authentications and transaction success.
+
+## transaction.initializeLog()
+
+This function initializes transaction logging.
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.initializeLog();
+```
+## transaction.getTimeSpent()
+
+This function returns the amount of time since the transaction was requested.
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.getTimeSpent();
+```
+
+## transaction.logPageOpen()
+
+Logs the time when the transaction page was opened
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logPageOpen();
+```
+
+## transaction.logAuthWindowOpen()
+
+Logs the time when the transaction authentication window was opened
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logAuthWindowOpen();
+```
+
+## transaction.logAuthWindowClose()
+
+Logs the time when the transaction authentication window was closed
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logAuthWindowClose();
+```
+
+## transaction.logChannelSwitch(channelName)
+
+Log switch to a channel with name `channelName`
+
+**Example**
+
+```js
+// initialize transaction
+...
+	transaction.logChannelSwitch('card');
+```
+## transaction.logValidationErrors(inputs)
+
+Log validation errors on an array of `inputs`
+
+**Example**
+
+```js
+// initialize transaction
+...
+	transaction.logValidationErrors(['card number']);
+```
+
+## transaction.logInput(fieldName)
+
+Log when a customer filled a certain input field
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logInput('card number');
+```
+
+## transaction.logAttempt(channel)
+
+Log when a customer makes an attempt on a channel
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logAttempt('card');
+```
+
+## transaction.logBankSelect(bankName)
+
+Log what bank the user selected while trying to pay with a bank account
+
+**Example**
+
+```js
+// initialize transaction
+...
+transaction.logBankSelect('Access Bank');
+```
+
+## transaction.logError(message)
+
+Log when a customer encounters an error while attempting to pay
+
+**Example**
+
+```js
+// initialize transaction
+try {
+  // initialize transaction
+  // attempt to charge transaction
+} catch(error) {
+  transaction.logError(error.message);
+}
+```
+
+## transaction.logAuth(authType)
+
+Log when a customer needs to be authenticated.
+
+**Example**
+
+```js
+// attempt a charge and get a response
+
+if (response.status === 'auth') {
+  // log the authentication required
+  transaction.logAuth(response.data.auth);
+}
+```
+
+## transaction.logSuccess()
+
+Log when a customer has successfully completed a transaction
+
+**Example**
+
+```js
+// attempt a charge and get a response
+
+if (response.status === 'success') {
+  transaction.logSuccess();
+}
+```
+## transaction.logPending()
+
+Log when a transaction status is `pending`
+
+**Example**
+
+```js
+// attempt a charge and get a response
+
+if (response.status === 'pending') {
+  transaction.logPending();
+}
+```
+
+## transaction.logPageClose()
+
+Log when a customer closes a payment page
+
+**Example**
+
+```js
+// listen for a page close event
+transaction.logPageClose();
+```
+
+## transaction.saveReferrer(referrerUrl)
+
+Log the page a payment page was opened from
+
+**Example**
+
+```js
+// initialize transaction
+transaction.saveReferrer(document.referrer)
+```
+
+## # Checking transaction status
+
+## transaction.requery()
+
+Used to check the status of a transaction
+
+**Example**
+
+```js
+await transaction.requery();
+// responds with a ChargeResponse
+```
+
+## # Toolkit
+
+Houses various utility functions like error resolutions, supported banks, and celebrations.
+
+## Toolkit.contents
+
+Returns an array of possible parameters to be used with the `Toolkit.fetch()` and their corresponding usage
+
+**Example**
+
+```js
+import { Toolkit } from 'checkout-js';
+
+Toolkit.contents();
+
+// output
+[{
+  key: 'banks', 
+  usage: 'Returns a list of banks that can be used to complete checkout'
+  }, {
+    key: 'celebrations',
+    usage: 'Returns a list of upcoming celebrations'
+  }, {
+    key: 'resolutions',
+    usage: 'Returns a list of known errors, mapped to their suggested resolutions'
+  }]
+```
+
+## Toolkit.fetch(option)
+
+A static method on the `Toolkit` class that operates on valid `keys` from `Toolkit.contents()` and returns data consistent with the `usage` of each `key`.
+
+**Example**
+
+```js
+import { Toolkit } from 'checkout-js'
+...
+const celebrations = await Toolkit.fetch('celebrations')
+
+// celebrations.data returns a list of National celebrations and their dates:
+{
+  "2018-06-07": "Happy Valentine's Day ❤️",
+  "2018-03-06": "Happy Independence Day 🇬🇭",
+  "2018-04-01": "Happy Easter 🙏",
+  "2018-05-01": "Happy Worker's Day 💪",
+  "2018-05-27": "Happy Children's Day 👶",
+  "2018-05-29": "Happy Democracy Day 🇳🇬",
+  "2018-06-15": "Barka da Sallah 🎉",
+  "2018-10-01": "Happy Independence Day 🇳🇬",
+  "2018-12-25": "Merry Christmas 🎉",
+  "2018-12-26": "Happy Boxing Day 🎁"
+}
+...
+
+// params is an optional object which defaults to {pay_with_bank: '1'} if no value is passed.
+const banks = await Toolkit.fetch('banks', params)
+
+// banks.data returns;
+[{
+    name: "Access Bank"
+    slug: "access-bank"
+    code: "044"
+    longcode: "044150149"
+    gateway: "emandate"
+    pay_with_bank: true
+    active: true
+    is_deleted: null
+    country: "Nigeria"
+    currency: "NGN"
+    type: "nuban"
+    id: 1
+    createdAt: "2016-07-14T10:04:29.000Z"
+    updatedAt: "2016-07-14T10:04:29.000Z"
+}, { ... } ...]
+```
+
+## # Validating a Card
+
+## Card.validate({ number, cvv, month, year })
+
+A static method on the `Card` class that takes an object containing `cardNumber` , `cvv`, `month` and `year` returning an object specifying if the card is valid.
+
+**Example**
+
+```js
+import { Card } from 'checkout-js';
+
+const cardDetails = {
+  number: '4084084084084081',
+  cvv: '408',
+  month: '03',
+  year: '21',
+}
+
+Card.validate(cardDetails);
+
+// output
+// { isValid: true, errors: [] }
+```
+
+## Card.isNumberValid(cardNumber)
+
+A static method on the `Card` class that takes a card number and returns true if the card number is valid.
+
+**Example**
+
+```js
+import { Card } from 'checkout-js';
+
+const cardNumber = '4084084084084081';
+
+Card.isValidNumber(cardNumber);
+
+// output
+// true
+```
+
+## Card.getType(cardNumber)
+
+A static method on the `Card` class that takes a card number and returns the type of card for a valid card number
+
+**Example**
+
+```js
+import { Card } from 'checkout-js';
+
+const cardNumber = '4084084084084081';
+
+Card.getType(cardNumber);
+
+// output
+// {type: 'visa', maxLength: 19}
+
+// output for invalid card number
+// {type: null, maxLength: 0}
+```
+
+## Card.isCvvValid(cvv)
+
+A static method on the `Card` class that takes a cvv returns true if cvv supplied is valid
+
+**Example**
+
+```js
+import { Card } from 'checkout-js';
+
+const cvv = '408';
+
+Card.isCvvValid(cvv);
+
+// output
+// true
+```
+
+## Card.isExpiryValid(month, year)
+
+A static method on the `Card` class that takes an expiry month and year returning `true` if valid
+
+**Example**
+
+```js
+import { Card } from 'checkout-js';
+
+const expiryMonth = '10';
+const expiryYear = '2020'
+
+Card.isExpiryValid(expiryMonth, expiryYear);
+
+// output
+// true
+```
+
+## # Validating a bank account
+
+## BankAccount.validate({ bankId, accountNumber, accountType })
+
+A static method that takes an object containing `bankId`, `accountType` and `accountNumber`, returning an object specifying the validity of the account number supplied.
+
+**Example**
+
+```js
+import { BankAccount } from 'checkout-js';
+
+// valid accountTypes: BankAccount.types
+// valid bankIds: Toolkit.fetch('banks')
+const bankDetails = {
+  bankId: 1,
+  accountType: 'nuban',
+  accountNumber: '0011163526'
+}
+
+BankAccount.validate(bankDetails);
+
+// output
+// {isValid: true, errors: []}
+```
+
+## BankAccount.isValidNubanAccount(accountNumber)
+
+A static method on the `BankAccount` class that takes a bank account number and returns `true` if it is a valid ‘nuban’ account number.
+
+**Example**
+
+```js
+import { BankAccount } from 'checkout-js';
+
+const accountNumber = '08033991672'
+
+BankAccount.isValidNubanAccount(accountNumber);
 
-Clone this repository
+// output
+// true / false
+```
 
-    git clone git@github.com:PaystackHQ/checkout-js.git
+## # Charge Responses
 
-Install dependencies with:
+This is the format in which all charge responses in `checkout-js` are returned. A charge response will always have a `status` and a `message`.
 
-    npm install
+## Success
 
-# Development
+This means that the charge attempt was successful
 
-The source code can be found in the `src/` folder.
+**Example**
 
-# Testing
+```js
+{
+  status: 'success',
+  message: 'Transaction successful',
+  data: { ... }
+}
+```
 
-Testing is done with Jest. To test your changes, run
+## Auth
 
-    npm test
+This means that additional authentication has to be carried out to complete the transaction
 
-To run tests in watch mode, run
+**Example**
 
-    npm run test:watch
+```js
+{
+  status: 'auth',
+  message: 'Authentication Required', // for 3DS, this would be the 3DS redirect URL
+  data: {
+    auth: 'pin' // can either be [pin, otp or 3DS]
+  }
+}
+```
 
-# Build
+## Failed
 
-Checkout JS is built with Rollup. To build, run the command
+This means that the charge attempt failed
 
-    npm run build
+**Example**
 
-You can also specify an environment to build for: `dev`, `staging`, or `production`. Configuration variables are set in `src/config.js`.
+```js
+{
+  status: 'failed',
+  message: 'Transaction failed',
+  errors: [],
+  /* the 'error' object is only available if a card transaction fails. It tells us the bank the failed card was issued by. You can use this to suggest that your customer pays with their bank account, if it's one of the supported banks in Toolkit.fetch('banks') */
+  error: {
+    bank: 'Guaranty Trust Bank'
+  }
+}
+```
 
-# Deployment
+# Additional Notes
 
-Checkout JS is deployed to three environments:
+### Pusher
 
-- Staging: [https://js-studio.paystack.co/v1/checkout.js](https://js-studio.paystack.co/v1/checkout.js)
-- Production: [https://js.paystack.co/v1/checkout.js](https://js.paystack.co/v1/checkout.js)
-- npm: [@paystack/checkout-js](https://npmjs.com/package/@paystack/checkout-js)
+This library uses a third party service, Pusher, to listen for API responses in the following methods
 
-# Releases
+- `Transaction.listenFor3DSCharge`
+- `Transaction.listenForIbankCharge`
+- `Transaction.listenForUSSDCharge`
+- `Transaction.listenForQRCharge`
+- `Transaction.listenForMobileMoneyCharge`
+- `Transaction.listenForDigitalBankMandateCharge`
 
-Checkout JS is automatically packaged and published to the NPM registry on every push to the `master` and `dev` branches.
+However, this does not work on non-Paystack domains so you have to use the `transaction.requery()` method to check the status of the transaction when using any of those payment methods. 
 
-The `master` branch is publised under the `latest` tag and can be installed by running `npm i @paystack/checkout-js@latest` while the `dev` branch is published under the `dev` tag and can be installed using `npm i @paystack/checkout-js@dev`
+### Error Handling
 
-All published versions are listed here on NPM https://www.npmjs.com/package/@paystack/checkout-js
+To ensure higher success rates, errors and failure messages should not be taken as an indication of finality, for example when a payment fails on the Paystack Checkout, the customer is prompted to retry via the same payment method or an alternative payment method.