Web Card SDK V2

Integrating Card SDK (V2) in Your Website

Introducing the TAP Card JavaScript library v2, an enhanced and streamlined solution tailored for crafting seamless payment experiences. This powerful tool simplifies the integration process, empowering you to effortlessly create secure payment flows within your web applications while ensuring the utmost protection of sensitive card information.

In this guide, we will walk you through the step-by-step process of integrating the latest TAP Card JavaScript library v2, showcasing its enhanced features such as simplified integration and efficient card tokenization.

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 get the required public keys to start the Web Card SDK v2 integration.

Integrate Web Card SDK v2

In this section we will guide you on how to implement Web Card SDK v2 using Vanilla JS.

Here is a demo page for trying out our new Card SDK in beta.

The SDK will display the available payment methods and gather payment details from your customers.


Embed the SDK Script

In your HTML file, you have to embed the Card SDK v2 as per the below:

<script src="https://tap-sdks.b-cdn.net/card/1.0.2/index.js"></script>

Create a DOM element for Card SDK v2

Create a DOM container element within your checkout page to specify where the Card SDK will be displayed, assigning it an identifier.

<div id="card-sdk-id"></div>

🚧

We highly advise not to embed the Card SDK within an iframe element to avoid potential complications.

Configure the Card SDK

For this implementation to work, initialize essential functions and constants provided within the SDK. These functions and constants facilitate the seamless integration of the Web Card SDK into your web page.

Once the initialization is complete, you can proceed to configure the Web Card SDK to tailor the checkout flow according to your specific requirements and preferences. This involves creating a comprehensive configuration setup covering various aspects of the checkout process to enhance the user experience for your customers.

In this section we will list the parameters that can be used as well as completing the configuration of the SDK.

Parameters

Here you can see all the parameters that can be passed to the Card SDK configuration.

NameTypeR/ODescription
publicKeystringrequiredThe public Key provided by Tap
merchantobjectoptionalThe merchant object
merchant.idstringoptionalThe merchant's Tap id.
transactionobjectrequiredThe transaction object
transaction.amountnumberrequiredThe transaction amount.
transaction.currencystringrequiredThe transaction currency.
customerobjectoptionalThe customer object
customer.idstringoptionalThe Tap customer ID
customer.nameArrayoptionalThe customer name object
customer.name[index].langstringoptionalThe customer name language
customer.name[index].firststringoptionalThe customer first name
customer.name[index].laststringoptionalThe customer last name
customer.name[index].middlestringoptionalThe customer middle name
customer.name.nameOnCardstringoptionalThe customer name on card
customer.name.editablebooleanoptionalTo control the name editing
customer.contactobjectoptionalThe customer contact object
customer.contact.emailstringoptionalThe customer email
customer.contact.phoneobjectoptionalThe customer phone object
customer.contact.phone.countryCodestringoptionalThe customer phone country code
customer.contact.phone.numberstringoptionalThe customer phone number
acceptanceobjectoptionalThe acceptance object
acceptance.supportedBrandsstring[]optionalThe supported brands
acceptance.supportedCardsstring[]optionalThe supported cards.

Ex:

  • "ALL", to accept both Debit and Credit cards.
  • ["DEBIT"], to accept only Debit cards.
  • ["CREDIT"], to accept only Credit cards.
fieldsobjectoptionalThe fields object
fields.cardHolderbooleanoptionalTo show/hide the card holder name
addonsobjectoptionalThe addons object
addons.loaderbooleanoptionalTo show/hide the loader on the card
addons.saveCardbooleanoptionalTo show/hide the save card option
addons.displayPaymentBrandsbooleanoptionalTo show/hide the payment brands section
interfaceobjectoptionalThe interface object
interface.localestringoptionalThe card locale
interface.themestringoptionalThe card theme
interface.edgesstringoptionalThe card edges
interface.directionstringoptionalThe card direction
onReadyfunctionoptionalCallback function runs when card becomes ready
onFocusfunctionoptionalCallback function runs when card is focused
onBinIdentificationfunctionoptionalCallback function runs when bin is identified
onValidInputfunctionoptionalCallback function runs when card inputs are valid
onInvalidInputfunctionoptionalCallback function runs when card inputs are invalid
onErrorfunctionoptionalCallback function runs when card has an error
onSuccessfunctionoptionalCallback function runs when card is successfully done

Card SDK Configuration

In this section we showcase the JavaScript code needed to configure the Web Card SDK v2.

Note that it is mandatory to pass the public key linked to your Tap account, which you can find by logging in to Tap's business dashboard, as well as specifying your Tap merchant ID.

const { renderTapCard, Theme, Currencies, Direction, Edges, Locale } = window.CardSDK
const { unmount } = renderTapCard('card-sdk-id', {
  publicKey: 'pk_test_...', // Tap's public key
  merchant: {
    id: 'merchant id'
  },
  transaction: {
    amount: 1,
    currency: Currencies.SAR
  },
  customer: {
    id: 'customer id', //Tap's customer ID with syntax cus_xxx
    name: [
      {
        lang: Locale.EN,
        first: 'Test',
        last: 'Test',
        middle: 'Test'
      }
    ],
    nameOnCard: 'Test',
    editable: true,
    contact: {
      email: '[email protected]',
      phone: {
        countryCode: '971',
        number: '52999944'
      }
    }
  },
  acceptance: {
    supportedBrands: ['AMERICAN_EXPRESS', 'VISA', 'MASTERCARD', 'MADA'], //Remove the ones that are NOT enabled on your Tap account
    supportedCards: "ALL" //To accept both Debit and Credit
  },
  fields: {
    cardHolder: true
  },
  addons: {
    displayPaymentBrands: true,
    loader: true,
    saveCard: true
  },
  interface: {
    locale: Locale.EN,
    theme: Theme.LIGHT,
    edges: Edges.CURVED,
    direction: Direction.LTR
  }
})

Add the Event Handlers

To keep the payers aware of what is happening during the payment process, make sure to add the callback functions in the SDK configuration. This will allow you to know the the SDK is ready to be used, if the inputs entered are valid or not, if there is any errors and in the success flow, it will display the tokenized card that the customer has submitted.

  onReady: () => console.log('onReady'),
  onFocus: () => console.log('onFocus'),
  onBinIdentification: (data) => console.log('onBinIdentification', data),
  onValidInput: (data) => console.log('onValidInputChange', data),
  onInvalidInput: (data) => console.log('onInvalidInput', data),
  onError: (data) => console.log('onError', data),
  onSuccess: (data) => console.log('onSuccess', data),
  onChangeSaveCardLater: (isSaveCardSelected) => console.log(isSaveCardSelected, " :onChangeSaveCardLater") // isSaveCardSelected:boolean

Full HTML Code Sample

In this section you will find the full code sample of the HTML and JavaScript codes that you can use to easily test the integration. Make sure to use the correct public key linked to your Tap account.

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<script src="https://tap-sdks.b-cdn.net/card/1.0.0-beta/index.js"></script>

		<title>card demo</title>
	</head>
	<body>
		<div id="card-sdk-id"></div>
		<script>
			const { renderTapCard, Theme, Currencies, Direction, Edges, Locale } = window.CardSDK
			const { unmount } = renderTapCard('card-sdk-id', {
				publicKey: 'pk_test_...',
				merchant: {
					id: 'merchant id'
				},
				transaction: {
					amount: 1,
					currency: Currencies.SAR
				},
				customer: {
					id: 'customer id',
					name: [
						{
							lang: Locale.EN,
							first: 'Test',
							last: 'Test',
							middle: 'Test'
						}
					],
					nameOnCard: 'Test Test',
					editable: true,
					contact: {
						email: '[email protected]',
						phone: {
							countryCode: '20',
							number: '1000000000'
						}
					}
				},
				acceptance: {
					supportedBrands: ['AMERICAN_EXPRESS', 'VISA', 'MASTERCARD', 'MADA'],
					supportedCards: "ALL"
				},
				fields: {
					cardHolder: true
				},
				addons: {
					displayPaymentBrands: true,
					loader: true,
					saveCard: true
				},
				interface: {
					locale: Locale.EN,
					theme: Theme.LIGHT,
					edges: Edges.CURVED,
					direction: Direction.LTR
				},
				onReady: () => console.log('onReady'),
				onFocus: () => console.log('onFocus'),
				onBinIdentification: (data) => console.log('onBinIdentification', data),
				onValidInput: (data) => console.log('onValidInputChange', data),
				onInvalidInput: (data) => console.log('onInvalidInput', data),
           onChangeSaveCardLater: (isSaveCardSelected) => console.log(isSaveCardSelected, " :onChangeSaveCardLater"), // isSaveCardSelected:boolean
				onError: (data) => console.log('onError', data),
				onSuccess: (data) => console.log('onSuccess', data)
			})
		</script>
	</body>
</html>

Get the Tap Token

After the Web Card SDK is fully configured and initialized, you need to create a submit button in order to submit the payment form. In order to tokenize the card added, you have to also import the tokenize method that is available within the SDK to complete this step.

In this section we will share the methods can be used within the SDK as well as calling the tokenize method to convert the raw card details to tokens.

Card Methods

To leverage the full functionality of the SDK, it's essential to comprehend the array of methods at your disposal. Here, we'll outline each method alongside its purpose, followed by guidance on incorporating them into your codebase.

Methods List

NameDescription
resetCardInputsReset the card inputs
saveCardSave the card data
tokenizeTokenize the card date
updateCardConfigurationUpdate the card configuration. For example updating the currency to show the supported payment methods ex: transaction: {currency: "USD" } will shows only the payment methods that supports USD currency
updateThemeUpdate the card theme by sending in the parameter "dark" or "light"
loadSavedCardLoad the saved card by card id

Import Methods in your Code

You can import all the required methods from the SDK as follows:

const { 
  tokenize, 
  resetCardInputs,
  saveCard,
  updateCardConfiguration,
  updateTheme,
  loadSavedCard } = window.CardSDK

Tokenize the Card

To submit the card details that were added in the Web Card v2, you need to create a button, and on this button you need to add the onclick event and call the tokenize method from the SDK to the Tap token.

You can either call the tokenize method in the JavaScript code or directly in the onclick event of the button, in the HTML file, as per the below.

<button id="card-v2" onclick="window.CardSDK.tokenize()">Submit</button>

Tokenize Result

In the onSucess callback you will receive the Tap token that you need pass to the source.id of the create a charge API to complete the payment with the added card.

Here is a sample of the token response that you will receive

{
    "id": "tok_xuCp45241437ANEj31F4P426",
    "status": "ACTIVE",
    "created": 1714747065426,
    "object": "token",
    "live_mode": false,
    "type": "CARD",
    "purpose": "CHARGE",
    "used": false,
    "card": {
        "id": "card_cfeU45241437Saus3j947433",
        "object": "card",
        "on_file": false,
        "address": {},
        "funding": "CREDIT",
        "fingerprint": "B1XZy88SUJkZ4%2FP%2Bn16CZO7k2l34nUHNoephQ0T94hA%3D",
        "brand": "VISA",
        "scheme": "VISA",
        "category": "",
        "exp_month": 1,
        "exp_year": 39,
        "last_four": "1111",
        "first_six": "411111",
        "first_eight": "41111111",
        "name": "Test"
    },
    "payment": {
        "id": "card_cfeU45241437Saus3j947433",
        "on_file": false,
        "card_data": {
            "exp_month": 1,
            "exp_year": 39,
            "last_four": "1111",
            "first_six": "411111",
            "first_eight": "41111111",
            "address": {}
        },
        "fingerprint": "B1XZy88SUJkZ4%2FP%2Bn16CZO7k2l34nUHNoephQ0T94hA%3D",
        "scheme": "VISA",
        "category": ""
    },
    "merchant": {
        "id": "12345"
    }
}