Documentation

Apple Pay Payment API

This documentation is intended for Apple Pay in iOS apps. For information about using Apple Pay on the web see Apple Pay with Collect.js

Supported Processors

Apple Pay supports Global Payments East - EMV, Test CC Processor, First Data Nashville, Chase Paymentech Salem, Chase Paymentech Tampa, EPX, Vantiv Now Worldpay eCommerce - Host Capture (Litle & Co), Global Payments Canada, First Data Nashville North, Vantiv Now Worldpay Core - Terminal Capture, Paymentech Salem Dev, Vantiv Now Worldpay eCommerce - Terminal Capture (Litle & Co.), First Data Nashville North V2, FACe - Vantiv Pre-Live, FACe - Vantiv, First Data Compass, TSYS - EMV, Credomatic Web Service, Credomatic Web Service Dev, First Data Rapid Connect Nashville North - EMV, First Data Rapid Connect Cardnet North - EMV, First Data Rapid Connect Nashville - EMV, FACe - Vantiv (Next Day Funding), Elavon viaConex, First Data Rapid Connect Omaha - EMV, Elavon EISOP UK/EU - EMV, American Express Direct UK/EU - EMV, Credorax ePower EU - EMV, Worldpay APACS UK/EU - EMV, First Data APACS UK/EU - EMV, Lloyds Cardnet APACS UK/EU - EMV, Barclaycard HISO UK/EU - EMV, AIBMS APACS UK/EU - EMV, Global Payments APACS UK/EU - EMV, Checkout.com Unified Payments, BancEdge Payments and FACe - Worldpay Core processors configured for e-commerce.

Configuring Apple Pay

Creating an Apple Merchant ID
First, you must obtain an Apple Merchant ID before you can generate the Certificate Signing Request that Apple requires. You will need to set up an Apple Merchant ID in your iOS Developer Account. Follow these steps to complete the setup:

1. Create a new Merchant ID

   Go to Apple’s Developer Portal and log in to the Member Center to create a new Merchant ID.

2. Open Certificates, Identifiers, and Profiles

   Navigate to the Certificates, Identifiers, and Profiles area of the Member Center, and then begin the Register Merchant ID process.

3. Set the Merchant ID in your gateway Control Panel

   Set the Apple Merchant ID within your gateway Control Panel under Settings -> Apple Pay.

Generating the Certificate Signing Request
Next, you will need to associate a Certificate with the Merchant ID in Apple’s Developer Portal. After downloading the Certificate Signing Request from the gateway’s options page, follow these steps.

1. Edit the Merchant ID

   In Apple’s Developer Portal, click on the Merchant ID and then click “Edit”.

2. Create the certificate

   Click “Create Certificate”.

3. Continue to the CSR upload page

   You are obtaining a CSR file from a Payment Provider so you will not have to create one. Click “Continue” to proceed to the upload page.

4. Upload the gateway CSR file

   Click “Choose File…” and select the Gateway.certSigningRequest file you downloaded from the gateway’s options page.

How to Obtain Apple Pay Payment Data

PassKit provides the payment data in the (PKPayment *)payment that is returned to your app’s paymentAuthorizationViewController:didAuthorizePayment:completion method. The Apple Pay encrypted payment data is found in payment.token.paymentData.

payment.token.paymentData is a binary (NSData) object, so you must encode it as a hexadecimal string before it can be passed to the Gateway.

Passing Apple Pay Payment Data

To submit a payment with Apple Pay, send the encrypted token data into the applepay_payment_data variable. There is no need to decrypt the data in your app. Only the Gateway will have access to the private key that can decrypt the token.

Apple Pay data can also be stored in the Customer Vault or used to prepare a recurring subscription.

Notes

When passing in applepay_payment_data, you should not include the variables ccnumber or ccexp; they are extracted from the token data.

Important Note: The authorization amount must match the amount the customer approves in the app. If you pass in a currency, that must also match the currency approved in the app. If omitted, the currency from the app is used.

For working example code, including how to obtain the PKPayment object and how to pass a simple transaction to the Gateway, download the sample project.

Stored Credential and Recurring Note: When Apple Pay data is added to the Customer Vault or used to create a subscription, an immediate transaction is triggered. This transaction is necessary because Apple Pay data includes a time-sensitive cryptogram, which may expire before the next transaction is ready otherwise. The transaction defaults to a sale in the amount the customer approved on their device, or a $0 authorization if that amount was$0. You can switch the transaction to be authorization-only instead by setting the “type” variable to “auth”.

Apple Pay for recurring and Customer Vault requires use of a compatible processor. Please check with support for the latest list of supported platforms.

Variables

Variable Name	Description
applepay_payment_data	The encrypted Apple Pay payment data (payment.token.paymentData) from PassKit encoded as a hexadecimal string

Troubleshooting

If you receive the error “Failed to decrypt Apple Pay data. Ensure that the Apple Pay Merchant ID is correct in the Gateway Settings and that the certificate was generated from a Gateway Certificate Signing Request.”, try these steps:

1. Verify the Merchant ID in Apple's portal

   Verify that the Merchant ID that Apple has in the developer portal exactly matches the Merchant ID in the Gateway’s settings.

2. Verify your app's merchantIdentifier

   Verify that your app’s PKPaymentRequest’s merchantIdentifier exactly matches the Merchant ID in the Gateway’s settings.

3. Check the enabled Merchant ID in your target settings

   Ensure that the correct Merchant ID is checked in the Apple Pay section of the Capabilities tab in your project’s target settings.

4. Create a new Merchant ID if needed

   Try creating a new Merchant ID. Reusing an existing Merchant ID with a new certificate may sometimes cause issues with encryption.

Merchant-Decrypted Data

Merchants who already have a certificate registered with Apple and decrypt the data themselves can relay it through repurposed 3-D Secure fields:

Variable Name	Description
decrypted_applepay_data	Set to “1” to indicate decrypted data is being sent.
ccnumber	The dPAN number from the Apple Pay token.
ccexp	Expiration date associated with the dPAN.
cavv	The cryptogram extracted from the Apple Pay token.
eci	The eCommerce Indicator value from the Apple Pay token, when available.