Increasingly, developers need to build applications that support multiple platforms and payment channels. In this example we focus on how to integrate Apple Pay with Vantiv’s eCommerce payment APIs.
About Apple Pay
Apple Pay is a mobile payment and digital wallet service by Apple that lets users make payments from their mobile phone using the iPhone 6, iPhone 6 Plus and Apple Watch-compatible devices.
With Apple Pay, the consumer’s phone stores a tokenized payment credential (or multiple credentials), that can be used to support transactions either at an NFC enabled point of sale or via a mobile application.
- In the first case, where Apple Pay is used at a contactless point of sale device supporting NFC, integration “comes for free” from a developer perspective. Apple Pay uses existing payment rails, and Apple Pay transactions are processed by Vantiv automatically, just like any other NFC payment transaction.
- In the second case, users can make payments from a mobile application using a pay button. This is referred to as an in-app payment. Vantiv provides a simplified approach to supporting Apple Pay in-app payments that leverages Vantiv’s existing eCommerce APIs. Developers can use the same approach to accept in-app payments that they may already use for payments on eCommerce websites.
How it works
To enable Apple Pay payment from within their iOS applications, developers should follow the steps outlined in the Apple Pay Guide.
Apps that use Apple Pay need to enable Apple Pay capabilities in Xcode. Developers will need to register a merchant identifier and set up cryptographic keys with Apple, which are used to send payment data to your server. Developers can learn more about this process at the Apple developer website.
Within the app, the developer will create a payment request using Apple’s PKPaymentRequest class explained in the Vantiv Apple Pay Guide. A payment request consists of a list of summary items that describe what is being purchased, a list of available shipping methods if applicable, a description of what shipping information the user needs to provide, and information about the merchant and payment processor.
As explained in the Apple documentation, not all Apple devices support Apple Pay. Before processing a payment request, developers should use the canMakePayments and canMakePaymentsUsingNetworks methods in the PKPaymentAuthorizationViewController to ensure that the device supports Apple Pay and that it is able to make payments using a supported payment network (Visa, MasterCard or American Express). If the user can’t make payments, it’s the responsibility of the developer to not show the Apple Pay button, and optionally fall back to another method of payment such as presenting a web form to accept payment powered by Vantiv’s eCommerce platform.
Processing Apple Pay payments with Vantiv
Vantiv supports multiple options for handling the PKPaymentToken provided by Apple Pay. Vantiv recommends using one of our own methods for decrypting the PKPaymentToken because this relieves developers of the responsibility of creating and maintaining and public and private keys.
Vantiv supports two approaches for integrating with Apple Pay where Vantiv decrypts the token:
- If developers are using Vantiv’s eProtect (PayPage) technology already in their mobile applications, they should consider using eProtect for Apple Pay. This approach is discussed in the eProtect Integration Guide in the eCommerce documentation.
- A second, similar method, which still allows you to submit the PKPaymentToken without decryption, involves sending the eCommerce Authorization / Sale transaction with the PKPaymentToken key values encoded in an XML <applepay> structure. This is support in Vantiv’s eCommerce API. The Authorization / Sale transaction would be made just like any Vantiv eCommerce transaction except that it will include the additional fields in the <applepay> structure so that Vantiv can process the payment transaction. Details are available in the Vantiv eCommerce integration guide.
In both of these scenarios, your Vantiv Implementation Consultant will provide a CSR (Certificate Signing Request) to use in your registration process with Apple Pay. The CSR provides Apple Pay with the public key used for encryption, while Vantiv retains the private key used for decryption.
Once Vantiv sends the approval/decline message back to your server, it is the developer’s responsibility to relay the approval/decline message back to the mobile application.
The <applepay> structure (shown below) is a child of Authorization, Sale and registerTokenRequest methods in the Vantiv eCommerce API.
<applepay> <data>User Name</data> <header> <applicationData>Base64 Hash of App Data Property</applicationData> <ephemeralPublicKey>Base64 Encoded Ephemeral Public Key</ephemeralPublicKey> <publicKeyHash>Base64 Hash of Public Merchant Key Cert</publicKeyHash> <transactionId>Hex Transaction Id</transactionId> </header> <signature>Signature of Payment and Header Data</signature> <version>Payment Token Version Info</version> </applepay>
If a transaction is processed that includes the <applepay> structure, a corresponding <applepayResponse> structure will be returned as part of the associated authorizationResponse, saleResponse or registerTokenResponse message.
<applepayResponse> <applicationPrimaryAccountNumber>App PAN</applicationPrimaryAccountNumber> <applicationExpirationDate>App PAN Exp Date</applicationExpirationDate> <currencyCode>Currency Code</currencyCode> <transactionAmount>Amount of Transaction</transactionAmount> <cardholderName>Name of cardholder</cardholderName> <deviceManufacturerIdentifier>Id of Device Mfr</deviceManufacturerIdentifier> <paymentDataType>Type of Payment Data</paymentDataType> <onlinePaymentCryptogram>Payment Cryptogram</onlinePaymentCryptogram> <eciIndicator>eCommerece Indicator</eciIndicator> </applepayResponse>