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 obtain a Certificate Signing Request (CSR) file from CardConnect. You use this file to generate an Apple Pay Payment Processing Certificate, and you must send the public key file for this certificate to CardConnect.

Contact integrationdelivery@cardconnect.com to request the required CSR file. 

Note that this process can take up to 5 business days.

  • You must must create and configure an Apple Pay Merchant ID, and you must create a provision an Apple Pay Merchant ID (with appropriate Identifier and Profile) and Payment Processing 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.

Limitations

The CardPointe Gateway's Apple Pay integration includes some important limitations. Before you begin, review the following limitations to ensure that this solution meets your needs.

Transaction Limitations

The following Apple Pay transaction types, as described here, are currently not supported by the CardPointe Gateway:

  • Partial shipment
  • Fixed subscription
  • Flexible frequency subscription
  • Managed subscription 

Token Limitations

As described here, CardSecure decrypts the Apple Pay payment data and generates a token that your application uses to make an authorization request to the CardPointe Gateway. Note the following limitations for Apple Pay tokens:

  • A unique Apple Pay Device Personal Account Number (DPAN) is generated for each transaction; therefore, tokens generated for the unique DPAN should not be stored for reuse or saved to customer profiles.
  • You must tokenize the Apple Pay payload within 2 minutes of retrieval. Attempting to tokenize an expired Apple Pay payload results in an "decryption failure" error response from CardSecure.
  • You must retrieve a new Apple Pay payload for each tokenization attempt. Tokens generated for Apple Pay payloads are valid for a single authorization.

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 the Certificates, Identifiers & Profiles link.
  3. Select the Merchant IDs link under Identifiers.
  4. Click the + icon to create a new Merchant ID.
  5. Enter a description and identifier and click Continue.
  6. Click Register.

Creating an Apple Pay Payment Processing Certificate and Uploading the CSR

  1. Log in to https://developer.apple.com/account.
  2. Select the Certificates, Identifiers & Profiles link.
  3. Select the All link under Certificates.
  4. Click the + icon to create a new certificate.
  5. Select the Apple Pay Certificate radio button and click Continue.
  6. Select the Merchant ID that you created in the previous procedure.
  7. Click Create Certificate in the Payment Processing Certificate section.
  8. On the Generate Certificate page, click Choose File..., select the CSR file that you received from CardConnnect (apple-pay-.csr), and click Continue.
  9. Click Download to download the signed public key file (apple_pay.cer) and click Done.
  10. Send the apple_pay.cer file that you downloaded in the previous step 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.

A unique Apple Pay Device Personal Account Number (DPAN) is generated for each transaction. Tokens generated for the unique DPAN should not be stored for reuse or saved to customer profiles.

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 empty (for example, "...&echash=&ecpublickeyhash=<publicKeyHash>").

You must tokenize the Apple Pay payload within 2 minutes of retrieval. Attempting to tokenize an expired Apple Pay payload results in an "decryption 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.