Articles in this section

Apple Pay with ChipDNA Direct

Jennifer Murphy
  • Updated
Follow

Apple Pay SDK Setup

Visit our Apple Pay page on creditcall.com.

Download the Apple ChipDNA Direct SDK.

Payment Process Flow

  1. 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().
  2. User clicks the Apple Pay button. The app creates a payment request, which includes the final amount total, and displays the payment sheet.
  3. Allow the user to amend/update information.
  4. User confirms details and authorizes the payment.
  5. 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.
  6. 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

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.

applePay2.png

 

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.

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.

examplePaymentSheet.png       cardEaseXMLExampleAppPaymentSheet.png

(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:

  1. Sign in to iTunes Connect (via https://developer.apple.com/account)
  2. On the homepage, click Users and Roles.
  3. Click Sandbox Testers.
  4. Select “+” to set up your tester accounts.
  5. Complete the Tester Information form and click Save.
  6. 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:

  1. Make sure you are signed out of any iCloud accounts on your test device. Sign into your test device with your sandbox tester account.
  2. Go to Wallet and tap Add Credit or Debit Card.
  3. 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
  4. 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.

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.