Introduction

With goSell Checkout, small merchants can effortlessly integrate Tap Payments into their websites, providing a hassle-free experience for both the merchant and their customers.

This integration supports two convenient options:

1. Redirection to Tap Hosted Payment Page: Allow customers to smoothly transition to Tap's hosted payment page for a secure and straightforward payment process.
2. Lightbox Popup: Enable a user-friendly lightbox popup, offering quick access to card and device payments without the need for intricate setup.

The integration caters to diverse programming preferences with support for two languages: React.js and Vanilla.js. This flexibility ensures that merchants can choose the integration method that best suits their technical requirements.

Setup your Tap Account

If you haven't done so already, please register your business in Tap Payments in order to setup your own account and required API keys to start the goSellCheckout integration.

Requirements

To integrate the Tap Payments GoSellCheckout, ensure your development environment meets the following prerequisites:

• If you're using lower version of mobx 6, please integrate with goSellCheckout v1.6.3 instead.

Installation

As mentioned, there are 2 types of using the goSellCheckout Web SDK, either to redirect to Tap hosted payment page, where all the payment methods are available, or a lightbox mode where a popup will appear on the merchant's website with the payment form to pay, however ApplePay is not supported in this one.

In this section, we will demonstrate the step by step guide on both integration, in React.js and Vanilla JS.

Import the Scripts and Packages

To start the integration, you need to import the script of goSellCheckout in Vanilla JS or install the package then import it in the code, if you are using React.js. Here are the code snippets that you need to use for both.

Vanilla JS

Add the JavaScript library which allows front end developers to setup the payment gateway on their stores easily by adding a very basic snippet of code using the following script tag:

<script type="text/javascript" src="https://goSellJSLib.b-cdn.net/v2.0.0/js/gosell.js"></script>

React.js

Install goSell package from npm if you are integration with React.js framework by running the following command in the terminal.

npm i @tap-payments/gosell

Once the installation is done, you can import the package in your code like below.

import { GoSell } from "@tap-payments/gosell";

📘

Before starting, make sure to add the JavaScript Library in a server-side environment, otherwise, the credit card section will not work.

Choose the goSellCheckout Mode

To kickstart the process, establish the configurations of your payment gateway as soon as your page loads. Create a handler object using goSell.config() to tailor the settings to your specific needs. Then, effortlessly showcase the transaction results by invoking goSell.openLightBox() or goSell.openPaymentPage() upon a click event.

1. goSell.openLightBox(): represents the popup mode, where all payment methods are supported except for ApplePay.
2. goSell.openPaymentPage(): represents the redirection to Tap hosted checkout page, where all payment methods are enabled without any exception.

Choose your transaction Mode

In the goSellCheckout, we have introduced 4 different transaction modes, depending on how and what the merchant is trying to achieve after the customer submits his card details.

Those transaction modes are charge, authorize, save card and tokenize. We will dive deep into each one of them, stating its description and parameters to be added.

Charge

• Description: Use this transaction mode to directly charge the customer. This is the default and straightforward mode for regular transactions.
• Type: Object
• Configuration:

  property name	Type	Status	Default value	Description
  saveCard	boolean	optional		Payer can save the credit for future purpose. Customer phone number is required to save the card, values can be one of (true or false). In order to use this service, please contact our Team to get the access.
  threeDSecure	boolean	optional		The 3D Secure request status for a particular charge, values can be one of (true or false)
  description	string	optional		Charge Description.
  statement_descriptor	string	optional		Payer Statement Descriptor.
  reference	object	optional	{ transaction: "txn_0001", order: "ord_0001" }	Transaction & order numbers of your reference.
  destinations	object	optional		It's used to transfer funds from one business to another with in tap. add the following block in charge or authorize object with the destination details: destinations: { destination: [ { id: "0000000", amount: 00, currency: "KWD", }, ], }
  metadata	string	optional		Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
  receipt	object	optional	{ email: false, sms: true }	Whether receipt email or sms to be send to the payer or not
  redirect	string	required		After payment completed, payer will be redirected to this url (KNET and 3D secure charge request required, Redirect url)
  post	string	required		After payment completed, goSell Gateway will post the charge response to the this url

Authorize

• Description: Initiates authorization, temporarily holding funds in the customer's bank account. The merchant has the flexibility to either capture the authorized amount or void the transaction within a 7-day period.
• Type: Object
• Configuration:

  property name	Type	Status	Default value	Description
  auto	object	required	{ type: "VOID", time: 100 }	You can create CAPTURE or VOID successful authorized transactions by goSell after a specified time period, You can use the auto object in the authorize request. Time should be defined in hours, Minimum 1 hour and Maximum 168 hours.
  saveCard	boolean	optional		Payer can save the credit for future purpose. Customer phone number is required to save the card, values can be one of (true or false). In order to use this service, please contact our Team to get the access.
  threeDSecure	boolean	optional		The 3D Secure request status for a particular charge, values can be one of (true or false)
  description	string	optional		Charge Description.
  statement_descriptor	string	optional		Payer Statement Descriptor.
  reference	object	optional	{ transaction: "txn_0001", order: "ord_0001" }	Transaction & order numbers of your reference.
  destinations	object	optional		It's used to transfer funds from one business to another with in tap. add the following block in charge or authorize object with the destination details: destinations: { destination: [ { id: "0000000", amount: 00, currency: "KWD", }, ], }
  metadata	string	optional		Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
  receipt	object	optional	{ email: false, sms: true }	Whether receipt email or sms to be send to the payer or not
  redirect	string	required		After payment completed, payer will be redirected to this url (KNET and 3D secure charge request required, Redirect url)
  post	string	required		After payment completed, goSell Gateway will post the charge response to the this url

Tokenize

• Description: Offers enhanced control for merchants. When customers add their card details in the SDK, the card gets tokenized. Merchants can then choose to either authorize or charge the card or simply just save it for future transactions. Basically, used to save credit/debit cards in goSell gateway.
• Type: Value
• Configuration: There's not configurations for this mode.

Save Card

• Description: Allows the secure storage of customer card details with Tap, though not commonly utilized.
• Type: Value
• Configuration: There's not configurations for this mode.

General Configuration

Here we will demonstrate how to configure the general details and specify the information that can be passed to the goSellCheckout Web SDK to perform a transaction, like the currency, the items and amount to be paid, the customer details and few others.

Gateway

It's a required object field for the JS library. It includes the general settings of the payment gateway, which you can see below:

Customer

It's a required object field for the JS library. Includes the customer details, it's required for charge, authorize & saveCard modes only.

Order

It's a required object field for the JS library. Includes the order details, it's required for charge, authorize modes only.

Transaction

It's a required object field for the JS library. Includes the transaction mode and it's configurations.

Receive Callback Notification

It's an optional field, goSell.showResult() which defines an action or a callback after showing the transaction result in redirect page. It will return the transaction result in a JSON.

GoSellCheckout Full Configuration Example

In this section, we will add 2 examples of the goSellCheckout SDK configuration, one in Vanilla JS and the other in React.js, both using the charge transaction mode.

Main File

Here, you can see the full example, where we add the script of goSell, then we created both button options, for lightbox or Tap hosted payment page, finally adding the configuration discussed in the previous section, where you need to pass the public key of your own Tap account that you get from your dashboard.

<html>
<head>
    <title>goSell Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" />
    <link rel="shortcut icon" href="https://goSellJSLib.b-cdn.net/v2.0.0/imgs/tap-favicon.ico" />
    <link href="https://goSellJSLib.b-cdn.net/v2.0.0/css/gosell.css" rel="stylesheet" />
</head>
<body>
    <script type="text/javascript" src="https://goSellJSLib.b-cdn.net/v2.0.0/js/gosell.js"></script>

    <div id="root"></div>
    <button id="openLightBox" onclick="goSell.openLightBox()">open goSell LightBox</button>
    <button id="openPage" onclick="goSell.openPaymentPage()">open goSell Page</button>

    <script>

    goSell.config({
      containerID:"root",
      gateway:{
        publicKey:"pk_test_Vlk842B1EA7tDN5QbrfGjYzh",
        language:"en",
        contactInfo:true,
        supportedCurrencies:"all",
        supportedPaymentMethods: "all",
        saveCardOption:false,
        customerCards: true,
        notifications:'standard',
        callback:(response) => {
            console.log('response', response);
        },
        onClose: () => {
            console.log("onClose Event");
        },
        backgroundImg: {
          url: 'imgURL',
          opacity: '0.5'
        },
        labels:{
            cardNumber:"Card Number",
            expirationDate:"MM/YY",
            cvv:"CVV",
            cardHolder:"Name on Card",
            actionButton:"Pay"
        },
        style: {
            base: {
              color: '#535353',
              lineHeight: '18px',
              fontFamily: 'sans-serif',
              fontSmoothing: 'antialiased',
              fontSize: '16px',
              '::placeholder': {
                color: 'rgba(0, 0, 0, 0.26)',
                fontSize:'15px'
              }
            },
            invalid: {
              color: 'red',
              iconColor: '#fa755a '
            }
        }
      },
      customer:{
        id:"cus_m1QB0320181401l1LD1812485",
        first_name: "First Name",
        middle_name: "Middle Name",
        last_name: "Last Name",
        email: "[email protected]",
        phone: {
            country_code: "965",
            number: "99999999"
        }
      },
      order:{
        amount: 100,
        currency:"KWD",
        items:[{
          id:1,
          name:'item1',
          description: 'item1 desc',
          quantity:'x1',
          amount_per_unit:'KD00.000',
          discount: {
            type: 'P',
            value: '10%'
          },
          total_amount: 'KD000.000'
        },
        {
          id:2,
          name:'item2',
          description: 'item2 desc',
          quantity:'x2',
          amount_per_unit:'KD00.000',
          discount: {
            type: 'P',
            value: '10%'
          },
          total_amount: 'KD000.000'
        },
        {
          id:3,
          name:'item3',
          description: 'item3 desc',
          quantity:'x1',
          amount_per_unit:'KD00.000',
          discount: {
            type: 'P',
            value: '10%'
          },
          total_amount: 'KD000.000'
        }],
        shipping:null,
        taxes: null
      },
     transaction:{
       mode: 'charge',
       charge:{
          saveCard: false,
          threeDSecure: true,
          description: "Test Description",
          statement_descriptor: "Sample",
          reference:{
            transaction: "txn_0001",
            order: "ord_0001"
          },
          metadata:{},
          receipt:{
            email: false,
            sms: true
          },
          redirect: "http://localhost/redirect.html",
          post: null,
        }
     }
    });

    </script>

</body>
</html>

import React, { Component }  from "react";
import { GoSell } from "@tap-payments/gosell";

class GoSellDemo extends Component {

  constructor(props){
    super(props);
  }

  callbackFunc(response){
    console.log(response);
  }

  render() {

    return (
      <div className="App">

      <button onClick={() => GoSell.openLightBox()}>open goSell LightBox</button>
      <button onClick={() => GoSell.openPaymentPage()}>open goSell Page</button>

        <GoSell
           gateway={{
             publicKey:"pk_test_Vlk842B1EA7tDN5QbrfGjYzh",
             language:"en",
             contactInfo:true,
             supportedCurrencies:"all",
             supportedPaymentMethods:"all",
             saveCardOption:true,
             customerCards: true,
             notifications:'standard',
             backgroundImg: {
              url: 'imgURL',
              opacity: '0.5'
            },
             callback: this.callbackFunc,
             labels:{
                 cardNumber:"Card Number",
                 expirationDate:"MM/YY",
                 cvv:"CVV",
                 cardHolder:"Name on Card",
                 actionButton:"Pay"
             },
             style: {
                 base: {
                   color: '#535353',
                   lineHeight: '18px',
                   fontFamily: 'sans-serif',
                   fontSmoothing: 'antialiased',
                   fontSize: '16px',
                   '::placeholder': {
                     color: 'rgba(0, 0, 0, 0.26)',
                     fontSize:'15px'
                   }
                 },
                 invalid: {
                   color: 'red',
                   iconColor: '#fa755a '
                 }
             }
           }}
           customer={{
             first_name: "First Name",
             middle_name: "Middle Name",
             last_name: "Last Name",
             email: "[email protected]",
             phone: {
                 country_code: "965",
                 number: "99999999"
             }
           }}
           order={{
             amount: 100,
             currency:"KWD",
             items:[{
               id:1,
               name:'item1',
               description: 'item1 desc',
               quantity:'x1',
               amount_per_unit:'KD00.000',
               discount: {
                 type: 'P',
                 value: '10%'
               },
               total_amount: 'KD000.000'
             },
             {
               id:2,
               name:'item2',
               description: 'item2 desc',
               quantity:'x2',
               amount_per_unit:'KD00.000',
               discount: {
                 type: 'P',
                 value: '10%'
               },
               total_amount: 'KD000.000'
             },
             {
               id:3,
               name:'item3',
               description: 'item3 desc',
               quantity:'x1',
               amount_per_unit:'KD00.000',
               discount: {
                 type: 'P',
                 value: '10%'
               },
               total_amount: 'KD000.000'
             }],
             shipping:null,
             taxes: null
           }}
           transaction={
             mode: 'charge',
             charge:{
              saveCard: false,
              threeDSecure: true,
              description: "Test Description",
              statement_descriptor: "Sample",
              reference:{
                transaction: "txn_0001",
                order: "ord_0001"
              },
              metadata:{},
              receipt:{
                email: false,
                sms: true
              },
              redirect: "REDIRECT_URL",
              post: null,
            }}
           />
      </div>
    );
  }
}

export default GoSellDemo;

Callback Redirection Page

If you want to show the customer the latest status of the transaction that they have just done after running the above configuration code, then you can create a Redirect page that you add in the redirect field of the transaction object that calls the following function goSell.showResult(). Here is a sample code for it:

<html>
  <head>
    <title>Show Result Demo</title>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"
    />

    <link
      rel="shortcut icon"
      href="https://goSellJSLib.b-cdn.net/v2.0.0/imgs/tap-favicon.ico"
    />
    <link
      href="https://goSellJSLib.b-cdn.net/v2.0.0/css/gosell.css"
      rel="stylesheet"
    />
  </head>
  <body>

    <script
      type="text/javascript"
      src="https://goSellJSLib.b-cdn.net/v2.0.0/js/gosell.js"
    ></script>

    <div id="root"></div>
    <script>
       goSell.showResult({
           callback: response => {
           console.log("callback", response);
         }
      });
    </script>
  </body>
</html>

import React, { Component } from "react";
import { GoSell } from "@tap-payments/gosell";

class Redirect extends Component {
  componentDidMount() {
    GoSell.showResult({
      callback: (response) => {
        console.log("callback", response);
      },
    });
  }

  render() {
    return (
      <div className="App">
        <GoSell />
      </div>
    );
  }
}

export default Redirect;


----------------OR-------------------
  

import React, { Component }  from "react";
import { GoSell } from "@tap-payments/gosell";

class Redirect extends Component {

 render() {
    return (
      <div className="App">
        <GoSell
          gateway={{
            callback: (response) => {
              console.log("callback", response);
            },
          }}
        />
      </div>
    );
  }
}

export default Redirect;

Github Example

Sample application integration is available in Example folder in our Github repository.