Apple Pay®
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 |
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 Initialize Payment in the API Reference section of this site.
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><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>
<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
addApplePayButton
functionWrite 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 toapplePay
, 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
andbuttonType
. - Use the
onClick()
event to call theonApplePaymentButtonClicked()
function with the name of yourpaymentCallback
function as a parameter. TheonApplePaymentButtonClicked()
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
addApplePayButton
functionOn 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
paymentCallback
functionWhen 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 Authorize Payment in the API Reference section 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 Authorize Payment in the API Reference section for more information about this response.
Updated 15 days ago