Instructions to follow before starting to integrate Apple pay into your mobile or web channel

We provide a web SDK which can be used by merchants to integrate Apple Pay button into the merchant's website using React JS or Vanilla JS. The button can be placed anywhere on the page. On click of the button, Apple Pay payment starts.

Prerequisites

In order for Apple Pay Web SDK to function, the domain name needs to be registered with Tap. Reach out to tap support team and provide your domain name(s) (including list of sub-domain(s)), where you wish to put the Apple Pay button. Once tap registers the domain, your public key respective to the domain will be generated and made available on the tap business dashboard. You will have to provide the respective pk_key and merchant ID inorder to initiate the Apple Pay Web SDK.

The next step is to make sure that the domain verification file is hosted on every domain(s) submitted.

🚧

Host your domain-verification file at the following path for each domain (or sub-domain) before you’re registering the domain with Tap:

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

The domain-verification file must be in place before you register with Tap

Ensure that the file is accessible via browser at the correct location. Example: https://abc.com/.well-known/apple-developer-merchantid-domain-association

Register Merchant Domain Name with Apple Pay

Tap Payments will register the merchant's domain name with Apple Pay on behalf of the merchant. The merchant needs to provide the domain name to Tap Payments support team for this registration. This step ensures that payments are processed with the Tap Apple Pay certificate without the need for the merchant to have access to Apple Developer portal and hence eliminates the need to share CSR/CER files between the two parties.

The merchant receives from Tap Payments a domain association file that needs to be added in the below path, following the guidelines of Apple.

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

🚧

Ensure the following are done correctly

1. The domain name(s) provided for registration should matche the domain(s) where Tap Payments Apple Pay Button SDK(s) are implemented. Any mismatch may result in payment failures.
2. Ensure that the file is accessible at the correct location. You can visit your own domain path to make sure that the contents of the file are visible through the respective link. Example: https://abc.com/.well-known/apple-developer-merchantid-domain-association

ApplePay Web SDK Integration

We have provided the ApplePay Web SDK codes, in both React.js and Vanilla JS providing merchants with more options depending on the programming language that they are using.

ApplePay Web SDK using React.js

The react module for Apple Pay WEB SDK is available through the NPM registry. Installation is done using the npm install command:

Install the Libraries

npm install @tap-payments/apple-pay-button

OR

yarn add @tap-payments/apple-pay-button

Example of the React.js Integration Code (ES6)

Below is the React.js example code that you can add in your project, noting that you need to pass the publicKey that is provided by Tap after you have shared the domain of your website.

Tap will also provide you with the merchant.id that needs to be passed in line 26 in the below code block, which represents your account ID at Tap. And make sure that the domain added is the exact one that you have given to Tap to whitelist.

import React from 'react'
import {
 ApplePayButton,
 ThemeMode,
 SupportedNetworks,
 Scope,
 Environment,
 Locale,
 ButtonType,
 Edges
} from '@tap-payments/apple-pay-button'

const App = () => {
 return (
  <ApplePayButton
   // The public Key provided by Tap
   publicKey={'pk_test_xxxxxxxxxxxxxxxzh'}
   //The environment of the SDK and it can be one of these environments
   environment={Environment.Development}
   //to enable the debug mode
   debug
   merchant={{
    //  The merchant domain name
    domain: 'example.com',
    //  The merchant identifier provided by Tap
    id: '1xxxxx8'
   }}
   transaction={{
    // The amount to be charged
    amount: '12',
    // The currency of the amount
    currency: 'KWD'
   }}
   // The scope of the SDK and it can be one of these scopes:
   // [TapToken,AppleToken], by default it is TapToken)
   scope={Scope.TapToken}
   acceptance={{
    // The supported networks for the Apple Pay button and it
    // can be one of these networks: [Mada,Visa,MasterCard], by default
    // we bring all the supported networks from tap merchant configuration
    supportedBrands: [SupportedNetworks.Mada, SupportedNetworks.Visa, SupportedNetworks.MasterCard]
         supportedCardsWithAuthentications : ["3DS"]
   }}
   // The billing contact information
   customer={{
    id: 'cus_xxx',
    name: [
     {
      //"en or ar",
      lang: Locale.EN,
      // "First name of the customer.",
      first: 'test',
      //"Last name of the customer.",
      last: 'tester',
      // "Middle name of the customer.",
      middle: 'test'
     }
    ],
    // Defines the contact details for the customer & to be used in creating the billing contact info in Apple pay request
    contact: {
     //"The customer's email",
     email: '[email protected]',
     //"The customer's phone number"
     phone: {
      //"The customer's country code",
      countryCode: '20',
      //"The customer's phone number
      number: '10XXXXXX56'
     }
    }
   }}
   //for styling button
   interface={{
    //The locale of the Apple Pay button and it can be one of these locales:[EN,AR]
    locale: Locale.EN,
    // The theme of the Apple Pay button and it can be one of
    // these values : [light,Dark], by default it is detected from user device
    theme: ThemeMode.DARK,
    // The type of the Apple Pay
    type: ButtonType.BUY,
    // The border of the Apple Pay button and it can be one of these values:[curved,straight]
    edges: Edges.CURVED
   }}
   // optional (A callback function that will be called when you cancel
   // the payment process)
   onCancel={() => console.log('cancelled')}
   // optional (A callback function that will be called when you have an error)
   onError={(err) => console.error(err)}
   // optional (A async function that will be called after creating the token
   // successfully)
   onSuccess={async (token) => {
    // do your stuff here...
    console.log(token)
   }}
   // optional (A callback function that will be called when you button is clickable)
   onReady={() => {
    console.log('Ready')
   }}
   // optional (A callback function that will be called when the button clicked)
   onClick={() => {
    console.log('Clicked')
   }}
  />
 )
}

ApplePay Web SDK with Vanilla JS

When implementing the below code block of the latest version of the ApplePay button to be added in your web application, make sure that you pass the publicKey and merchant.id that Tap Payments will provide to you to have it linked to your account. Moreover, please add the domain that you have provided to Tap to whitelist in order to eliminate any errors.

<!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" />
		<title>apple pay button</title>
		<link rel="stylesheet" href="https://tap-sdks.b-cdn.net/apple-pay/build-1.0.19/main.css" />
		<script src="https://tap-sdks.b-cdn.net/apple-pay/build-1.0.19/main.js"></script>
	</head>

	<body>
		<div id="apple-pay-button"></div>
		<script type="text/javascript">
			const { render, ThemeMode, SupportedNetworks, Scope, Environment, Locale, ButtonType, Edges } =
				window.TapApplepaySDK
			render(
				{
					publicKey: 'pk_test_7xxxxxxxxx',
					environment: Environment.Development,
					scope: Scope.TapToken,
					merchant: {
						domain: window.location.hostname,
						id: 'merchant_xxxxxxxxxx'
					},
					transaction: {
						currency: 'SAR',
						amount: '3'
					},
					acceptance: {
						supportedBrands: [SupportedNetworks.Mada, SupportedNetworks.Visa, SupportedNetworks.MasterCard],
						supportedCardsWithAuthentications: ['3DS']
					},

					customer: {
						id: 'cus_xxx',
						name: [
							{
								locale: 'en',
								first: 'test',
								last: 'tester',
								middle: 'test'
							}
						],
						contact: {
							email: '[email protected]',
							phone: {
								number: '10XXXXXX56',
								countryCode: '20'
							}
						}
					},
					interface: {
						locale: Locale.EN,
						theme: ThemeMode.DARK,
						type: ButtonType.BUY,
						edges: Edges.CURVED
					},
					onCancel: async () => {
						console.log('onCancel')
					},
					onError: async (error) => {
						console.log('onError', error)
					},
					onSuccess: async (data) => {
						console.log('onSuccess', data)
					},
					onReady: async () => {
						console.log('onReady')
					}
				},
				'apple-pay-button'
			)
		</script>
	</body>
</html>

Specify the Environment

In the Web SDK configuration, you can specify different values to indicate the environment you are working in. Choosing the correct environment based on your development stage is crucial. To determine the appropriate environment such as sandbox, beta, or production, please refer to the following guidelines:

Development Environment

Mark the environment as Development when you are still testing in sandbox mode using test cards.

publicKey={'pk_test_UnfAj31y9*******LtPc'}
environment={Environment.Development}
   merchant={{
    domain: 'qptesting.com.bh',
    id: '27475267'
   }}

Beta Environment

Mark the environment as Beta when you are in the process of QA live testing. This is usually used with live keys and live cards.

publicKey={'pk_live_2nDLY8eJ******VIm936P'}
environment={Environment.Beta}
   merchant={{
    domain: 'qptesting.com.bh',
    id: '27475267'
   }}

Production Environment

Once your website is in production and accessible to the customers, mark the environment as Production to show that you are fully live and ready to accept live payments with ApplePay.

publicKey={'pk_live_2nDLY8eJ******VIm936P'}
environment={Environment.Production}
   merchant={{
    domain: 'qptesting.com.bh',
    id: '27475267'
   }}

📘

The Tap Payments Apple Pay Button SDK is designed to simplify the integration process. It abstracts the complexity of working directly with Apple Pay APIs.

Handle the event when the Apple Pay button is clicked.

Implement the necessary event handling mechanism to capture the click event on the Apple Pay button. In the callback functions, you will see all the actions that are provided by the ApplePay Web SDK, noting that the onSuccess one will give you a result as data if the integration is working well. The data will contain the token ID in the syntax of tok_xxx, that needs to be passed in the source.id of the Charge API to complete the payment with ApplePay.

onCancel: async () => {
  console.log('onCancel')
},
  onError: async (error) => {
    console.log('onError', error)
  },
    onSuccess: async (data) => {
      console.log('onSuccess', data)
    },
      onReady: async () => {
        console.log('onReady')
      }

🚧

Safely store and transmit the token ID as it represents sensitive payment information. Follow industry-standard security practices to protect the token ID and prevent unauthorized access.

Use the token ID to create a charge by sending a request to the Tap Payments API.

Construct the Charges API request with the necessary parameters, including the token ID, amount, currency, and any additional information required.

Handle the API response to handle the charge status and perform any necessary actions on your web page.

📘

Check the Charges API response for the charge status and handle it accordingly. Update the user interface to reflect the payment status and provide

Handling Charge Status and Error Cases

When creating a charge and interacting with the Tap Payments API, it's essential to handle various charge status scenarios and error cases. This ensures that you can provide appropriate feedback to your users and handle any potential issues gracefully. Follow these guidelines for effective charge status handling:

Successful Charge: If the charge status is CAPTURED, update the user interface to indicate a successful payment. Provide confirmation details such as the transaction ID and any relevant information.

Failed Charge: If the charge status is any other status than CAPTURED, it is not success. Therefore update the user interface to indicate the failure and provide an error message explaining the reason for the failure. It's important to display user-friendly error messages to assist the user in resolving any issues.

Error Handling: In case of any API errors or network failures, handle them gracefully. Display an error message to the user, offering guidance on what to do next. Additionally, consider logging the error details for troubleshooting purposes.

📘

Remember to test the integration thoroughly in a development or staging environment before deploying it to production. This will help identify and address any issues or potential pitfalls in the integration.

Configurations

Should you encounter any difficulties or have specific questions, reach out to the Tap Payments support team for prompt assistance. Happy integrating!