Overview

This guide provides information for integrating Apple Pay acceptance with an iOS or web-based application. 

The Bolt Mobile iOS SDK supports the ability to generate a token from data retrieved by Apple Pay, simplifying the integration with your iOS app. 

Requirements

Before you begin, consider the following:

  • You must be boarded on the First Data Rapid Connect platform in order to utilize tokens created from Apple Pay data.
  • You must must provision an Apple Pay Merchant ID (with appropriate Identifier and Profile) and certificate prior to submitting tokenization requests.
  • Using either the Bolt Mobile iOS SDK or a combination of the CardSecure and CardPointe Gateway APIs, your solution must integrate CardSecure to tokenize Apple Pay data and the CardPointe Gateway to use the tokens in authorization requests.

Apple Pay Device Personal Account Number (DPAN) is uniquely generated per transaction. Tokens generated by CardConnect in this manner should not be stored individually or within customer profiles.

Configuring an Apple Pay Merchant Account

Perform the following procedures to create and configure an Apple Pay merchant account.

Creating an Apple Merchant ID

  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand navigation bar.
  3. Select Merchant IDs link under Identifiers on lefthand navigation bar.
  4. Select + icon on the top right to create a new Merchant ID.
  5. Enter a description and identifier and hit Continue.
  6. Select Register.

Creating an Apple Pay Certificate and Uploading the CSR

  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand nav bar.
  3. Select All link under Certificates on lefthand nav bar.
  4. Select + icon on the top right to create a new certificate.
  5. Select Apple Pay Certificate radio button and hit Continue.
  6. Select the Merchant ID that was created.
  7. Click Create Certificate in the Payment Processing Certificate section.
  8. Answer questions and/or hit Continue until the Generate Certificate page is reached.
  9. Select the Choose File... button, select the CSR provided by CardConnect ('apple-pay-.csr' from step above), then hit Continue.
  10. Select Download to download the signed public key and hit the "Done" button.
  11. Send the apple_pay.cer file that was downloaded to CardConnect.

To test your solution using test (non-production) Apple Pay data, you must use the Apple Pay Sandbox environment. Attempting to tokenize test data generated in the Xcode simulator will fail. See the Apple Pay Sandbox Testing documentation for more information.

Integrating Apple Pay using the Bolt Mobile iOS SDK

This topic provides information for adding Apple Pay to an iOS application using the Bolt Mobile iOS SDK.

Configuring the Application

Do the following to add the Apple Pay capability to your merchant ID and provision your application:

  1. Within your Apple Developer account, enable Apple Pay in your provisioning profile with the merchant ID you configured for CardConnect.
  2. Enable Apple Pay under Capabilities by selecting your merchant ID from the list. If it doesn’t appear, find the {app_name}.entitlements file that was generated and add a string with your merchant ID in the merchant IDs array key.
  3. Ensure your application is set up to run with your provisioning profile and run the application or use the simulator.

Creating a Custom Flow

CCCAPI includes a function called generateTokenForApplePay:completion:. This function takes the Apple Pay PKPayment object and generates a CardConnect token. For information on creating a custom workflow, see Apple's Apple Pay Programming Guide.

Creating an Integrated Flow

The Bolt Mobile SDK integrated UI supports a basic Apple Pay workflow. It handles display of the Apple Pay UI, token generation, and response of the result. Your application needs to make the authentication request using the API bridge class and forward the response.

The following procedure provides general guidance for creating an integrated Apple Pay workflow.

  1. Follow the initial setup described in the Apple Pay Programming Guide to enable Apple Pay in your application.
  2. Create a CCCPaymentRequest object and set your merchant ID and amount to applePayMerchantID and Total respectively. An additionalData parameter is provided that can be used to store a reference, typically a transaction or order number.
  3. Before displaying your CCCPaymentController, set your CCCPaymentRequest to its paymentRequest parameter.
  4. In your class that conforms to the CCCAPIBridgeProtocol, implement the following which should use the token provided to make your authentication request and return the result in the completion block:
CCC_authApplePayTransactionWithToken:completion
  1. You can add the optional function paymentController:finishedApplePayWithResult: to your CCCPaymentController delegate for notification of an Apple Pay transaction.
  2. You can also customize how the Apple Pay UI is displayed using your CCCTheme class and the parameters:
applePayButtonDescription, applePayButtonStyle and applePayButtonType.

Troubleshooting

If the Apple Pay button doesn’t appear on the initial payment controller screen, enable debug logging on CCCAPI. When the payment controller screen displays, it will include a debug log to help troubleshoot.

Some related log messages include:

  • “applePayMerchantID not set.”
  • “total not set or <= $0.”
  • “Device doesn’t support payments.”

Integrating Apple Pay using the CardSecure API

This topic provides information for adding Apple Pay to your website or application using the CardSecure API. Apple Pay tokenization makes use of CardSecure's RSA encryption capabilities. A similar decryption process handles the encrypted data returned from Apple.

Before you begin, review the Apple Pay Payment Token Format Reference.

Making a CardSecure Tokenization Request

To pass the Apple Pay payment token to CardSecure, your application must first parse the data to retrieve and the required properties and reformat them in an encoded string. Your application includes this string in the devicedata field in the CardSecure tokenize request.

CardSecure Request URL

https://<site>.cardconnect.com/cardsecure/api/v1/ccn/tokenize

CardSecure Request Method

POST

CardSecure Request Parameters

The following parameters are required in the tokenize request:

FieldDescription
devicedataA string including the Apple Pay payment token data.
encryptionhandlerThe decryption method for CardSecure to use to handle the encrypted data.

This must be EC_APPLE_PAY.

Do not URL encode the devicedata string. See the example later in this topic to ensure that you format the string properly.

Formatting the Apple Pay Tokenization Request

To use CardSecure to tokenize an Apple Pay payment token, you must pass specific properties from the payment token object to CardSecure in the devicedata field in the tokenization request. The devicedata string must be formatted as follows:

"devicedata":"<data>&ectype=apple&ecsig=<signature>&eckey=<ephemeralPublicKey>&ectid=<transactionId>&echash=<applicationDataHash>&ecpublickeyhash=<publicKeyHash>"

The sequence of the properties in the field is required and must match the order documented. 

The following table describes the order and correlation of each Apple Pay payment token property and its corresponding property in the devicedata string:

Position in Request String

CardSecure Request PropertyApple Pay Payment Token PropertyDescription
1

Not labeled

dataThe data string in the Apple Pay response, which includes the encrypted payment data. 


This field is the first value in the CardSecure request string and is not labeled.
2ectype
N/AThe encryption type, which must be apple. This field is not present in the Apple Pay payment token.
3ecsigSignatureThe signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.
4eckeyephemeralPublicKeyThe ephemeral public key bytes.
5ectidtransactionIdThe transaction identifier, generated on the device.
6echashapplicationData

This field is optional, but must be included if the applicationData is present in the Apple Pay payment token. 

applicationData is the hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is null, this value is omitted.

7ecpublickeyhashpublicKeyHashThis field is optional, but must be provided included in the Apple Pay payment token. publicKeyHash is the hash of the X.509 encoded public key bytes of the merchant’s certificate.

Version 1.0 of the Apple Pay API does not return the echash and ecpublickeyhash values. If you are using Version 1 of the Apple Pay API, do not include these values in your CardSecure tokenization request.

If you have an ecpublickeyhash, you must provide the echash property in your request, even if it is null.

You must tokenize the Apple Pay payload within 2 minutes of retrieval. Attempting to tokenize an expired Apple Pay payload results in an "encryption failure" error response from CardSecure.

Additionally, you must retrieve a new Apple Pay payload for each tokenization attempt. Tokens generated for Apple Pay payloads are valid for a single authorization.

Making a CardPointe Gateway Authorization Request

Once you obtain a token, you can pass that token in an authorization request to the CardPointe Gateway. See the CardPointe Gateway API for more information.