Apple Pay SDK Setup
- Payment Process Flow
- Good to Know
- You Will Need
- Configuration
- Setting up Apple Pay
- User Selects Pay with Apple Pay Button
- Testing/Sandbox Account
- Useful Links
Download the Apple ChipDNA Direct SDK.
Payment Process Flow
- Display the official Apple Pay button (or download the image files for iOS 8.3 and earlier) after checking if Apple Pay is available using
canMakePayments()
. - User clicks the Apple Pay button. The app creates a payment request, which includes the final amount total, and displays the payment sheet.
- Allow the user to amend/update information.
- User confirms details and authorizes the payment.
- On the device, Apple Pay sends the payment request to the Secure Element. The Secure Element adds the payment data for the specified card and merchant, creating an encrypted payment token. It then passes this token to Apple’s servers, where it is re-encrypted using your Payment Processing certificate. Finally, the servers pass the token back to your app.
- The token is then passed to Creditcall’s platform where it is decrypted and processed. A standard ChipDNA Direct response is returned.
Good to Know
Prior to starting, Apple’s App Review Guidelines should be read to ensure that your app complies.
PassKit is a framework which lets you add and manage passes in the user’s Wallet app. PassKit provides the APIs that your app will use to determine if it is running on a device with a Secure Element (a dedicated chip on the user’s device) and if the device has been provisioned with supported card schemes. If the device is Apple Pay capable, you should present the ‘Buy with Apple Pay’ button using the APIs supplied within PassKit (for apps). In addition, if the device is Apple Pay capable, but Apple Pay is not set up, you should present the ‘Set up Apple Pay’ button in place of the ‘Buy with Apple Pay button’. This will allow the user to easily set up Apple Pay.
Examples of Apple Pay buttons
It is worth noting that for iOS 8.3 and later, Apple Pay payment buttons must be created using only the Apple-provided API. Earlier versions must create their own buttons using only button artwork provided by Apple and follow the instructions for artwork use. For iOS 9, ‘Set up Apple Pay’ buttons can also be created. The Creditcall app targets iOS 8.3 and does not include the ‘Set up Apple Pay’ button.
When using the SDK, it is worth mentioning that if the device cannot connect to the platform (e.g. the device cannot connect to the Internet) the error message "Payment Not Completed" will display after the user presses the ‘pay’ button (e.g. ‘Pay with Touch ID’). You may want to consider implementing better error handling for this.
Important: There are identity guidelines that the integrator’s app must implement in order to comply with the Apple identity requirements. Please be aware, the Creditcall iOS SDK has not been developed with these guidelines in mind. However, it does implement the Apple Pay button as specified. There is also a checkout process that must be followed to ensure a positive user experience. Please be aware the Creditcall iOS SDK does not comply with these guidelines. For example, we do not display a ‘review transaction/summary page’ or display an order confirmation page after executing the transaction. The purpose of the SDK is to provide a working example of how to generate a ChipDNA Direct request for Apple Pay.
You Will Need
- Apple Developer Account - You can enroll here.
- A merchant ID – you will need to register a merchant ID with Apple. A merchant ID is an identifier which tells Apple Pay that you are able to accept payments.
- You will then need to generate a Payment Processing Certificate for your merchant ID by clicking on ‘edit’ and following the instructions to generate a certificate signing request (CSR) to obtain Public and Private keys. This certificate is used to encrypt and decrypt payment tokens.
- An App ID - create an App ID and enable Apple Pay.
- Create a provisioning profile and link it to your machine certificate and the App ID above.
- An Apple Pay compatible device.
- Sandbox Account with test cards. To create, follow these steps.
- New integrations will need to be set up on our platform. Please contact Integration Support (support@creditcall.com). You will need your merchant ID and payment processing certificate (public hash key) to hand.
Configuration
SDK
In CEXExampleApplePay.m, the initWithAccount
method sets a variable called merchantId
. Replace the placeholder text with your merchant ID.
-(CEXExampleApplePay*)initWithAccount:(NSString*)theTerminalID :(NSString*)theTransactionKey { self = [super init]; if (self) { terminalID = theTerminalID; transactionKey = theTransactionKey; name = @"Example Apple Pay"; merchantId = @"merchant.com.example.id"; } return self; }
Although this value is hard coded in the example app, in an official app, you may want to consider not doing so.
Xcode -> CardEaseXMLExample App -> General
Ensure that you have downloaded your provisioning profile.
Xcode -> CardEaseXMLExampleApp -> Capabilities
Ensure Apple Pay is enabled. You should see your merchant ID. Ensure the box is checked. Click the refresh button below and ensure all Apple Pay checks are ticked.
Setting up Apple Pay
Check the Device can process Apple Pay and Display Button
There are three methods for checking if the device is capable of processing Apple Pay, canMakePayments
, canMakePaymentsUsingNetworks
and canMakePaymentsUsingNetworks:capabilities
.
canMakePayments
– indicates whether the device supports the ability to process Apple Pay. For example, the hardware or parental controls allow it.canMakePaymentsUsingNetworks
– checks that the user has Apple Pay and payment cards set up and configured on their device. This is done by passing an array of payment networks that are supported by the merchant account.canMakePaymentsUsingNetworks:capabilities
– checks whether the user’s payment methods are compatible (not implemented in the SDK)
If the device is compatible and Apple Pay is set up on the device, display the official ‘Buy with Apple Pay’ button.
If the device is compatible and Apple Pay is not set up on the device, display the official ‘Set up Apple Pay’ button in place of the ‘Buy with Apple Pay’ button. This will allow the user to set up Apple Pay.
if ([PKPaymentAuthorizationViewController canMakePayments]){ NSLog(@"The device supports Apple Pay"); }if ([PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks:[_example supportedNetworks]]){ // Apple Pay is available and set up on the device [self displayBuyWithApplePayButton]; NSLog(@"canMakePaymentsUsingNetworks: YES"); } else { // Apple Pay is not available or hasn't been set up on the device self.exampleTextView.text = [self.exampleTextView.text stringByAppendingString:@"Apple Pay is not available or hasn't been set up on the device"]; NSLog(@"canMakePaymentsUsingNetworks: NO"); }
User Selects Pay with Apple Pay Button
Present the Payment Sheet
Upon pressing the Pay with Apple Pay button, a PKPaymentRequest will need to be created to present the payment sheet to the user. PassKit uses this to display the Payment Sheet.
(L) Example Payment Sheet and (R) Example Payment Sheet from CardEaseXMLExampleApp
The payment sheet must immediately follow the user tapping the Apple Pay button, without any interim screens or pop-ups. Your app should specify the contents of the payment sheet, deciding which information should be presented on this screen. The SDK implements only the mandatory fields.
NSArray *paymentSummaryItems = @[ [PKPaymentSummaryItem summaryItemWithLabel:@"<SUBTOTAL>" amount:[NSDecimalNumber decimalNumberWithString:@"9.99"]], [PKPaymentSummaryItem summaryItemWithLabel:@"<SHIPPING>" amount:[NSDecimalNumber decimalNumberWithString:@"9.99"]], // Last item in the array must store the grand total and the label must be the person or company to be paid [PKPaymentSummaryItem summaryItemWithLabel:@"<COMPANY/PAYEE NAME>" amount:[NSDecimalNumber decimalNumberWithString:@"19.98"]] ];
The instance property paymentSummaryItems
is an array of PKPaymentSummaryItem
objects that is used to summarize the amount of the payment, e.g. order total, shipping cost (for shipping cost you must use the PKShippingMethod
subclass), tax, and the grand total. It is not intended for listing individual items. Granular details of the item-by-item costs should be provided elsewhere in the app. The last item in the paymentSummaryItems
array must contain the grand total for the purchase. The PKPaymentAuthorizationViewController class will display it differently than the rest of the summary items. As a result, there are additional requirements placed on both its amount and its label.
- The grand total amount must be the sum of all the other items in the array. This amount must be greater than zero.
- Set the grand total label to the name of your company. This label is used to represent the person or company being paid.
- You must consider additional payment processor requirements such as a minimum or maximum payment amount.
The PKPaymentRequest
stores all the information required for an Apple Pay payment request. The SDK implements only the mandatory fields.
paymentRequest = [[PKPaymentRequest alloc] init]; // The following fields are mandatory paymentRequest.merchantIdentifier = [_example merchantId]; paymentRequest.supportedNetworks = [_example supportedNetworks]; paymentRequest.merchantCapabilities |= PKMerchantCapability3DS | PKMerchantCapabilityDebit; paymentRequest.countryCode = @"GB"; paymentRequest.currencyCode = @"GBP"; paymentRequest.paymentSummaryItems = paymentSummaryItems;
The instance property merchantCapabilities
is a bit field with four possible PKMerchantCapability
values. The Apple Pay developer documentation states that merchants using Apple Pay must support the 3-D Secure protocol. The following code indicates that the merchant supports both 3-D Secure protocol and debit cards.
paymentRequest.merchantCapabilities |= PKMerchantCapability3DS | PKMerchantCapabilityDebit;
You need to retrieve the Apple Pay token from the PKPayment
. This is found in the paymentData
property and is of type NSData. You will need to convert it to NSString for the ChipDNA Direct request:
NSString *applePayToken = [[NSString alloc] initWithData:payment.token.paymentData encoding:NSASCIIStringEncoding];
You are now ready to create a ChipDNA Direct authorization request with the following extended properties:
[request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"digital-wallet":@"applepay"]]; [request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"applepay-merchantid":merchantId]]; [request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"applepay-token":applePayToken]];
Processing the Payment
When creating the ChipDNA Direct request, you must set the following:
PKPaymentSummaryItem *finalSummary = [paymentRequest.paymentSummaryItems lastObject]; NSString *applePayToken = [[NSString alloc] initWithData:payment.token.paymentData encoding:NSASCIIStringEncoding]; CEXRequest *request = [[CEXRequest alloc] init]; request.softwareName = SOFTWARE_NAME; request.softwareVersion = SOFTWARE_VERSION; request.terminalId = terminalID; request.transactionKey = transactionKey; request.requestType = RequestTypeAuth; request.amount = [NSString stringWithFormat:@"%@", finalSummary.amount]; request.amountUnit = AmountUnitMajor; [request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"digital-wallet" value:@"applepay"]]; [request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"applepay-merchantid" value:merchantId]]; [request addExtendedProperty:[[CEXExtendedProperty alloc] initWithProperty:@"applepay-token" value:applePayToken]]; . . .
Now you will process the ChipDNA Request
CEXClient *client = [[CEXClient alloc] init]; [client addServerUrl:[[CEXServerUrl alloc] initWithUrl:[NSURL URLWithString:@"https://test.cardeasexml.com/generic.cex"] timeout:TIMEOUT]]; client.request = request; error = [client processRequest]; completitionBlock(error,client.response);
The transaction is then processed by the platform as a standard authorization.
Testing/Sandbox
https://developer.apple.com/support/apple-pay-sandbox/
To create a sandbox tester account, follow these steps:
- Sign in to iTunes Connect (via https://developer.apple.com/account)
- On the homepage, click Users and Roles.
- Click Sandbox Testers.
- Select “+” to set up your tester accounts.
- Complete the Tester Information form and click Save.
- Sign out of your Apple ID on all testing devices and sign back in with your new sandbox tester account.
For more information on how to create a sandbox tester account, see Setting Up User Accounts.
Important: Do not use the sandbox tester account to sign into iTunes, or the App Store. If you mistakenly do so, the sandbox account becomes invalid and can’t be used again as such. If this happens, create a new sandbox tester account with a new email address.
To get started, add a test card to Wallet:
- Make sure you are signed out of any iCloud accounts on your test device. Sign into your test device with your sandbox tester account.
- Go to Wallet and tap Add Credit or Debit Card.
- Using your test credentials, follow the steps to add a new test card using manual entry. A list of valid test cards can be found at the bottom of this webpage.
FPAN: 4761 1200 1000 0492
Expiration Date: 11/2022
CVV: 533 - After your card has been added, you may begin testing.
Note: To provision test cards on your device and use the sandbox, you will need to make sure that your device’s region is set to a country that supports Apple Pay.
Useful Links
Guides and sample code
Apple Pay Programming Guide
Guidelines for Apple Developer Program members who wish to incorporate Apple Pay into their websites
Identity guidelines and checkout process
Apple Pay developer landing page (links to various helpful articles)
Apple Pay Sandbox
Provides a really good, high-level step-by-step process of setting up Apple Pay.