Apple Pay Hosted Checkout

Overview

This document details the steps necessary to integrate Apple Pay Hosted Checkout with your site.
Contents
  • Server-Side Integration
    • Server Endpoint Creation
    • API Integration
  • Client-Side Integration
    • Adding Reference to iFields
    • Adding JavaScript Objects for Apple Pay button
    • Enabling Apple Pay

Prerequisites

Implementing Apple Pay Hosted Checkout

Server-Side Integration

Server Endpoint Creation

A server endpoint is needed in order to accept the Apple Payload from Hosted Checkout.
Step 1: Create an endpoint and method for API Integration on your Server side that takes the Apple Payload and makes a call to Cardknox.

API Integration

Below are the steps to integrate Apple Pay with the Cardknox API:
Once the consumer confirms the payment, Apple Pay API generates a token in a form of a JSON string.
Integration Steps:
  1. 1.
    Encode that token with Base64 encoding.
  2. 2.
    Set xCardNum field to the encoded token above.
  3. 3.
    Set xDigitalWalletType to ApplePay.
  4. 4.
    Set the remaining required fields:
    1. 1.
      xAmount the Transaction Amount.
    2. 2.
      xCommand - Set to one of the values that start with cc: like cc:sale, cc:auth, etc.
    3. 3.
      xBillFirstName
    4. 4.
      xBillLastName
    5. 5.
      xBillStreet if available
    6. 6.
      xBillCity if available
    7. 7.
      xBillState if available
    8. 8.
      xBillZip
For more details, please contact your Cardknox Representative.

Client-Side Integration

Adding Reference to iFields

Find the latest version of iFields at: https://cdn.cardknox.com/ifields/versions.htm​
Step 1: Add the iFields .js file after the <head> tag on your payment page:
1
<script src=https://cdn.cardknox.com/ifields/**ifields-version-number**/ifields.min.js></script>
Copied!

Adding JavaScript Objects for Apple Pay button

Step 1: Add the following JS snippet inside the <body> where Apple Pay button is desired.
1
<div id="ap-container">
2
</div>
Copied!
Step 2: Create JavaScript object that holds all the properties/methods required to process Apple Pay
1
const apRequest = {
2
buttonOptions: {
3
buttonContainer: "ap-container",
4
buttonColor: APButtonColor.black,
5
buttonType: APButtonType.pay
6
},
7
..............
8
initAP: function() {
9
return {
10
buttonOptions: this.buttonOptions,
11
merchantIdentifier: "<Your Identifier provided by Cardknox>",
12
requiredBillingContactFields: ['postalAddress', 'name', 'phone', 'email'],
13
requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'],
14
onGetTransactionInfo: "apRequest.onGetTransactionInfo",
15
onValidateMerchant: "apRequest.onValidateMerchant",
16
onPaymentAuthorize: "apRequest.onPaymentAuthorize",
17
onPaymentComplete: "apRequest.onPaymentComplete",
18
onAPButtonLoaded: "apRequest.apButtonLoaded",
19
isDebug: true
20
};
21
}
22
}
Copied!
For a full sample code please refer here.
Step 3: Implement desired callbacks.
For the list of available callbacks please refer to Apple Pay Object​
  • There are three main callbacks that required to be implemented a(the rest are optional):
    • onGetTransactionInfo - Calculates the total amount based on the Charge amount, Fees, Taxes, Shipping Costs, etc.
    • onValidateMerchant - A callback to be called to validate the Apple Pay Merchant.
    • onPaymentAuthorize - A callback that will be called after Consumer Pays and Apple returns a token with all the requested Consumer information like Billing Address, Shipping Address, etc. This is where you need to make an AJAX call to your server with the Apple Payload. The sample for making an AJAX call is below.
Sample Code for making Ajax Call
1
validateApplePayMerchant: function (url) {
2
return new Promise(function (resolve, reject) {
3
try {
4
var xhr = new XMLHttpRequest();
5
xhr.open('POST', "https://api.cardknox.com/applepay/validate");
6
xhr.onload = function () {
7
if (this.status >= 200 && this.status < 300) {
8
resolve(xhr.response);
9
} else {
10
reject({
11
status: this.status,
12
statusText: xhr.response
13
});
14
}
15
};
16
xhr.onerror = function () {
17
reject({
18
status: this.status,
19
statusText: xhr.statusText
20
});
21
};
22
xhr.setRequestHeader("Content-Type", "application/json");
23
xhr.send(JSON.stringify({ validationUrl: url}));
24
} catch (err) {
25
setTimeout(function () { alert("getApplePaySession error: " + exMsg(err)) }, 100);
26
}
27
});
28
},
29
authorize: function (request, methodName, isPaymentOn) {
30
return new Promise(function (resolve, reject) {
31
$.ajax({
32
method: "POST",
33
//contentType: "application/json",
34
url: <Your Url>,
35
data: {
36
request: JSON.stringify(request)
37
}
38
}).done(function (resp) {
39
if (!resp) {
40
reject({
41
status: 500,
42
statusText: "Invalid blank response"
43
});
44
} else if (resp.status !== 200) {
45
reject({
46
status: resp.status,
47
statusText: resp.statusText
48
});
49
} else if (!resp.response) {
50
reject({
51
status: 500,
52
statusText: "Response has no body"
53
});
54
} else {
55
resolve(resp.response);
56
}
57
}).fail(function (xhr, status, err) {
58
console.error("authorize failed", "\nxhr: " + xhr.status + "-" + xhr.statusText, "\nstatus:" + status, "\nerr:" + JSON.stringify(err));
59
reject({
60
status: xhr.status,
61
statusText: xhr.statusText
62
});
63
});
64
});
65
}
Copied!
For full sample code, please refer to Apple Pay iFields Integration​
Step 4: Create JavaScript function that will initialize iFields.
1
initAP: function() {
2
return {
3
buttonOptions: this.buttonOptions,
4
merchantIdentifier: "merchant.cardknoxdev.com",
5
requiredBillingContactFields: ['postalAddress', 'name', 'phone', 'email'],
6
requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'],
7
onGetTransactionInfo: "apRequest.onGetTransactionInfo",
8
onGetShippingMethods: "apRequest.onGetShippingMethods",
9
onShippingContactSelected: "apRequest.onShippingContactSelected",
10
onShippingMethodSelected: "apRequest.onShippingMethodSelected",
11
onPaymentMethodSelected: "apRequest.onPaymentMethodSelected",
12
onValidateMerchant: "apRequest.onValidateMerchant",
13
onPaymentAuthorize: "apRequest.onPaymentAuthorize",
14
onPaymentComplete: "apRequest.onPaymentComplete",
15
onAPButtonLoaded: "apRequest.apButtonLoaded",
16
isDebug: true
17
};
18
}
Copied!
initAP function above returns Request Object.

Enable Apple Pay

window.ckApplePay object - controls initialization of Apple Pay button
Method
Call Required
Description
enableApplePay
Yes
Initializes and enables Apple Pay Button. Takes EnableApplePayParams object
updateAmount
Conditional
Updates amount on Apple Sheet.
You can provide either All, One or None of the parameters for enableApplePay call.
  • initFunction Required - Either function name or function itself to initialize ApplePay.
  • amountField Optional - if specified, Apple Pay total amount will be automatically updated whenever amount has changed
  • amountField is not specified - in this case it’s up to you to provide the correct amount for Apple Pay. One of the ways to do it is to call window.ckApplePay.updateAmount manually.
​

EnableApplePayParams Object

Name
Type
Required
Description
initFunction
String|Object
Yes
Either function name or function itself to initialize ApplePay
amountField
String|Object
No
Field containing amount. Could be either name of the field (String) or field itself (Object)
​
1
ckApplePay.enableApplePay({
2
initFunction: 'apRequest.initAP',
3
amountField: 'amount'
4
});
Copied!

Questions?

Contact [email protected]​
Last modified 16d ago