Overview

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

The CardConnect iOS Mobile 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 CardConnect iOS Mobile 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.

Using the simulator with Apple Pay will not generate payment data and the tokenization attempt will fail.

Integrating Apple Pay using the iOS Mobile SDK

This topic provides information for adding Apple Pay to an iOS application using the CardConnect iOS Mobile 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 integrated UI supports a very 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 found in 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 tokenize Apple Pay data, your application makes a POST request using CardSecure's CR action code.

CardSecure Request URL

https://fts.cardconnect.com:6443/cardsecure/cs

CardSecure Request Method

POST

CardSecure Request Parameters

The following parameters are required in the URL string submitted to CardSecure:

All fields must be URL encoded.

PropertyValue
actionCR
dataEncrypted payment data payload
ectypeapple
eckeyephemeralPublicKey from Header keys of Payment Token
ecsigSignature of the payment and header data
ectidTransaction ID from Header keys of Payment Token
echashHash of the applicationData property of the original PKPaymentRequest object.
ecpublickeyhashpublicKeyHash

The following sample request should only be used to reference the format required for a valid CS request. Due to the time sensitivity of the ecsig parameter, this sample request will not provide a token. Additionally, this sample request does not contain the required echash key/value pair.

action=CR&data=6gPONejyRUnSopAAfh%2B%2B58n8B32groXzpqbNG8hsr9fz2l8Cpo7PW6I0ur5ZbcfTUa8j85d2OWn1ihLC0lD7cZBUPfvq24Y8aVJs7B2xYDJqnkYqQO77VSq%2FQNODsGyrkVwhw%2Br2HLntNhvRxkSDfKIJKuNwd0zPH%2F%2B78IszbYmmeeCJ11OAFHePcFKN6Ye1fBVtwKE41qRZWJkfbQBbIxf%2BWESOvOXv1Tq2hrVFcjLBwXeAgeSmGoal9kua1d44vK49I6cNtuk3QfNha6eOMbfZS4kac6CELpawVX95tQXoZ56PGE0kEIaOWaWiJ4hNBepWQP1b1g%2F5B%2BLRlb6YuHixQI%2FHChPqTPiJSvJL1W41DNaxzcV2%2BWdZNd3Yz69r04tprE2AadKgaffP&ectype=apple&ecsig=MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O%2F0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22%2FVdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB%2FwQCMAAwHwYDVR0jBBgwFoAUI%2FJJxE%2BT5O8n5sT2KGw%2Forv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB%2FjCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB%2FwQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw%2BSoyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6%2BW5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS%2B%2FOpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou%2Fee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT%2FVEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk%2BTvJ%2BbE9ihsP6K7%2FS5LMA8GA1UdEwEB%2FwQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH%2FBAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr%2F0F%2B3ZD3VNoo6%2B8ZyBXkK3ifiY95tZn5jVQQ2PnenC%2FgIwMi3VRCGwowV3bF3zODuQZ%2F0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggGLMIIBhwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoIGVMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE3MDcxODE4MjQzOVowKgYJKoZIhvcNAQk0MR0wGzANBglghkgBZQMEAgEFAKEKBggqhkjOPQQDAjAvBgkqhkiG9w0BCQQxIgQgTq8L0dWa9YROmIC9xQFXWHoSPAZBq1Yu%2F6Y4S6d3keUwCgYIKoZIzj0EAwIERjBEAiAUloVnCk6nG4EXPFxTiEk7gVgVcvXnqdqWn9RMrHNFfgIgF%2FObI%2FMqvgAe5cLeWfcZT4lQ1cOVBcBqqTQn%2Bs28zAcAAAAAAAA%3D&eckey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEu4QmOj9%2Br3vzR9fae%2B3c00uwaQpCUM3GDODgUC74aTDEI7RJG%2Bw6VQOABvdvUq0EkKiIc%2F%2B%2BE2BojyGRxr%2Bo0Q%3D%3D&ectid=745c61b5653902cc50925549c6f79e756b22b948dd99aa643ebfadf44c27bc3f

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.