Below is a guide to integrating Apple Pay with CellPoint Velocity API, which lets a customer use a payment method saved to their Apple Pay account.

Onboarding Checklist

The following table shows the onboarding responsibilities belonging to CellPoint Digital, Apple, and you the merchant:

Owner	Owner Responsibilities	Details
CellPoint Digital	• Client onboarding and configuration • Merchant onboarding with Apple	• Client setup - account and clientid • API authorization credentials • Configure redirect URLs for successful and failed transactions • API version • Supported country-id list • Gateway ID: `cellpointmobile`
Merchant / Apple	Production validation by Apple	• Web integration - Merchant to contact Apple to validate integration • Web integration or merchant app - Obtain `merchantid` from Apple once production review is complete • Provide Merchant and Payment certificate • Request production access

Iframe Requirements

Apple Pay requires that the payment page's origin match a domain that Apple has on file for the merchant. Because the iframe's URL will be a CellPoint Digital URL, you must register and verify CellPoint's domain and your domain with Apple. Review Apple's Preparing Merchant Domains for Verification guide before requesting registration.

Additionally, when adding the iframe to the merchant site, include the allow="payment" attribute, as below:

<iframe name="paymentpage" width="1024" height="700" allow="payment"/>

See our Iframe guide for more information on iframe integration.

Apple Pay Requirements

Before you start the API integration, you must follow the Apple Web Integration checklist and branding guidelines as follows:

Workflow

When using Apple Pay with CellPoint Velocity API, the workflow is as follows:

The customer navigates to the merchant's payment/checkout page.
The checkout page must include JavaScript functions that display the Apple Pay button and handle the callback from CellPoint.
While the checkout page is loading, the merchant sends an Initialize request to CellPoint's API. The Initialize response includes Apple Pay content in the wallets object.
The merchant page adds the Apple Pay content from the Initialize response to the <head> and <body> of the page.
The merchant page calls the JavaScript function that displays the Apple Pay button.
When the customer selects the Apple Pay button, the Apple Pay wallet opens.
When the customer selects a payment method from the Apple Pay wallet, CellPoint calls the callback function on the checkout page with the Apple Pay data as parameters.
The merchant's callback function sends an Authorize request to the CellPoint API with payment data in the body of the request.
The API returns a successful Authorize response, which confirms the success of the payment.

Integration

Complete the following steps to add Apple Pay to your Velocity API integration.

1. Initialize a payment

Endpoint: /mpoint/initialize-payment
Method: POST

When the customer navigates to your payment page, send a POST request to the /mpoint/initialize-payment endpoint of the CellPoint Digital API. For more information, see API Quick Start and our Initialize API Reference.

The code below is an example Initialize request body:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<initialize-payment account="[integer]" client-id="[integer]">
		<transaction order-no="CPM1601976034055" type-id="[integer]" >
			<amount currency-id="[integer]" countryid="[integer]">100</amount>
		</transaction>
		<client-info language="en" app-version="1.43" sdk-version="1.43" version="1.43" platform="HTML5">
			<mobile operator-id="[integer]" country-id="200">[mobile number]</mobile>
			<email>[email]</email>
			<customer-ref>[customer-ref]</customer-ref>
		</client-info>
	</initialize-payment>
</root>

The response includes a wallets object that contains the information required to display the Apple Pay option on your site, as shown in the example below. Note that, in the wallets object, within card, the value of name is set to Apple Pay:

<wallets>
    <card cvc-length="-1" cvcmandatory="false" dcc="false" enabled="true" id="15" installment="0" max-length="-1" min-length="-1" payment-type="3" preferred="false" presentment-currency="false" processor-type="3" psp-id="-1" state-id="1" typeid="15">
        <name>Apple Pay</name>
        <prefixes>
            <prefix id="164">
                <min>-1</min>
                <max>-1</max>
            </prefix>
        </prefixes>
        <url method="overlay"/>
        <head>&lt;script
        type='text/javascript'&gt; var debug = false; var countryCode = "GB"; var currencyCode =
        "GBP"; var merchantIdentifier = 'merchant.mytest.applepay.sandbox'; var displayName
        ="Holidays"; var totalAmount = "152"; var supportedNetword =
        ['VISA','DISCOVER','MASTERCARD','AMEX']; var supportedNetwork =
        ['VISA','DISCOVER','MASTERCARD','AMEX']; &lt;/script&gt; &lt;script type="text/javascript"
        src="https://myurl/js/applepay.js"&gt;&lt;/script&gt; &lt;style&gt;
        #applePay{width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50%
        50%;backgroundcolor:#000;background-size:60%;background-repeat:no-repeat} &lt;/style&gt;</head>
        <body>&lt;button type="button" id="applePay"&gt;&lt;/button&gt;</body>
        <auth-token>Auth-Token</auth-token>Apple Pay 
    </card>
</wallets>

"wallets": {
    "card": [
        {
            "cvc_length": "-1",
            "cvcmandatory": "false",
            "dcc": "false",
            "enabled": "true",
            "id": "15",
            "installment": "0",
            "max_length": "-1",
            "min_length": "-1",
            "payment_type": "3",
            "preferred": "false",
            "presentment_currency": "false",
            "processor_type": "3",
            "psp_id": "-1",
            "state_id": "1",
            "type_id": "15",
            "name": "Apple Pay",
            "prefixes": {
                "prefix": {
                    "id": "164",
                    "min": "-1",
                    "max": "-1"
                }
            },
            "url": {
                "method": "overlay"
            },
            "head": "<script type=\"text/javascript\"> var debug = false; var countryCode = 'MX'; var currencyCode = 'BRL'; var merchantIdentifier = \"merchant.cpd.applepay.sandbox\"; var displayName ='Arajet'; var totalAmount = '100'; var supportedNetword = [\"VISA\",\"MASTERCARD\"]; var supportedNetwork = [\"VISA\",\"MASTERCARD\"]; </script> <script type='text/javascript' src='https://storage.googleapis.com/bkt-cp-sit-ehpp2/11100/js/applepay.js'></script> <style> #applePay{width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50% 50%;background-color:#000;background-size:60%;background-repeat:no-repeat} </style>",
            "body": "<button type='button' id='applePay'></button>",
            "auth_token": "Auth-Token",
            "text": "Apple Pay"
        }
    ]

Capture the content of the following fields, which you will use in the next step to add the Apple Pay option to your site:

Field	Format	Parents	Description
`head`	String	`root: wallets: card`	The `head` tag's contents set your payment options and add CellPoint Digital's Apple Pay JavaScript library to your page.
`body`	String	`root: wallets: card`	The `body` element's contents create a `<div>` that you will use to display the Apple Pay button.

Also, capture the contents of the following fields in this Initialize response. You will use them to call /mpoint/authorize (in step 4 of this guide):

Field	Format	Parents	Description
`id`	Positive Integer	`root: transaction`	A unique transaction ID generated for the Initialize request. This identifies a transaction in CellPoint Digital's systems.
`type-id`	Positive Integer	`root: wallets: card`	A unique ID that identifies your configured payment methods. `type-id = 15` refers to Apple Pay in CellPoint Digital's systems.

2. Add the HTML from the Initialize response to your page

Add the contents of the head and body tags from the Initialize response to your payment page, like in the example below:

<head>
  <script type='text/javascript'> var debug = false; var countryCode = "GB"; var currencyCode = "GBP";
    var merchantIdentifier = 'merchant.mytest.applepay.sandbox'; var displayName ="Holidays"; var
    totalAmount ="152"; var supportedNetword = ['VISA','DISCOVER','MASTERCARD','AMEX']; var
    supportedNetwork = ['VISA','DISCOVER','MASTERCARD','AMEX']; </script>
  <script type="text/javascript" src="https://myurl/js/applepay.js"></script>
  <style>
    #applePay{width:150px;height:50px;display:none;border-radius:5px;background-image:-
    webkit-named-image(apple-pay-logo-white);background-position:50%
    50%;backgroundcolor:#000;background-size:60%;background-repeat:no-repeat} </style>
</head>
<body>
  <button type="button" id="applePay"></button>
</body>

You may need to set the display style to block for the Apple Pay button, as in the example below:

const applePayButton = document.getElementById('applePay');
if (applePayButton) {
    applePayButton.style.display = 'block';
}

3. Display the Apple Pay button on your page

3a. Write an `addApplePayButton` function

Write a function to display the Apple Pay button and send CellPoint your implementation details, as shown in the example below:

function addApplePayButton (applePay, paymentCallback) {
	const paymentsClient = getApplePaymentsClient();
	const button =
		paymentsClient.createButton({
		buttonColor: 'default',
		buttonType: 'buy',
		onClick: () => onApplePaymentButtonClicked(paymentCallback) });
	container.appendChild(button);
}

The addApplePayButton function should take the following two parameters:

Apple Pay Button Container ID - The value of the id property that you assigned to the <div> that will display the button. The Initialize response sets this value to applePay, but you can use any value, as long as it is the same as the div ID.
Payment Callback - The name of the function on your site that CellPoint will call to pass the card token to your application.

The addApplePayButton() function should perform the following actions:

Call the getApplePaymentsClient() function. This is part of the CellPoint JavaScript library that you loaded from the Initialize response.
Set the values of these createButton properties: buttonColor and buttonType.
Use the onClick() event to call the onApplePaymentButtonClicked() function with the name of your paymentCallback function as a parameter. The onApplePaymentButtonClicked() function is part of the CellPoint Digital Apple Pay JavaScript library.

The paymentCallback function accepts four parameters: paymentToken, paymentNetwork, preauthenticated, and billingAddress. CellPoint Digital will call the paymentCallback function to take the transaction details that CellPoint Digital receives from Apple and send them in an Authorize request. See step 4 for details.

3b. Call the `addApplePayButton` function

On the onLoad event, call the addApplePayButton() function with apple-pay-container-id and the name of your callback function as parameters, as shown in the sample code below:

<body>
  <div id={apple-pay-container-id} /}>
    <script>
    	function onLoad{window.addApplePayButton(apple-pay-container-id, paymentCallback )}
    </script>
</body>

Calling addApplePayButton() adds a functioning Apple Pay button to your page.

When your customer clicks the Apple Pay button, CellPoint Digital displays the Apple Pay window, which allows the customer to select a card from their Apple Pay wallet. When the customer selects a card, CellPoint returns the payment token and other transaction details to your paymentCallback method.

4. Write your `paymentCallback` function

When your customer selects a payment method from the Apple Pay wallet, CellPoint Digital calls your paymentCallback function and passes the payment data as parameters. Write your paymentCallback function to capture the payment data and send a POST request to the /mpoint/authorize-payment endpoint of the CellPoint Velocity API, as shown in the example below:

const paymentCallback = (paymentObject, paymentNetwork, billingAddress) => {
    //Send an Authorize request with the returned data in the request body.
  };

The paymentCallback function should takes the following parameters:

paymentObject - The tokenized card data from the Apple Pay wallet.
paymentNetwork - The payment network that CellPoint will use to authorize the payment.
billingAddress - The customer's billing address for transaction verification purposes.

See our Authorize API Reference for details about sending the request.

5. Confirm success

You can confirm that payment was successful when you receive a successful Authorize response.

See the sample Authorize success response below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2005">3d verification required</status>
    <parsed-challenge>
        <action type-id="11">
            <url content-type="application/x-www-form-urlencoded" method="POST" type-id="1">https://3dsn.sandbox.safecharge.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL3Zob2xzLm1lc2Iuc2l0LmNwbS5kZXYvbXBvaW50L2FnZ3JlZ2F0b3IvbnV2ZWkvdGhyZWVkLXJlZGlyZWN0P2ludm9pY2UtaWQ9NzgzMTEwMCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiYTg0NWY2MzktYWM3Ny00N2I5LTk2YzItMzBlNWExYjIxMmJhIiwiYWNzVHJhbnNJRCI6ImE1NDU4ZDhlLTIzZmEtNDVhNi1iZjkwLTFlMDJlYjg3ODQwNSIsImRzVHJhbnNJRCI6Ijg2ZmIwMjU4LTY2YzctNGMzNC04NDE1LTRlZGQ5MTUwNzMxOCIsImRhdGEiOm51bGwsIk1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAifQ==</url>
            <hidden-fields>
                <creq>eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE4NDVmNjM5LWFjNzctNDdiOS05NmMyLTMwZTVhMWIyMTJiYSIsImFjc1RyYW5zSUQiOiJhNTQ1OGQ4ZS0yM2ZhLTQ1YTYtYmY5MC0xZTAyZWI4Nzg0MDUiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0</creq>
            </hidden-fields>
        </action>
    </parsed-challenge>
    <return-url>https://vhols.mesb.sit.cpm.dev/mpoint/aggregator/nuvei/threed-redirect?invoice-id=7831100</return-url>
</root>

See our Authorize API Reference for more information about this response.