Support for Apple Pay In-App payments with MercuryPay is also referred to as Vantiv’s OmniChannel for Integrated Payments solution. This is an “In-App” mobile payments solution for developers currently using Vantiv’s MercuryPay platform for ecommerce applications.
It is described as an OmniChannel solution because it supports Vantiv's OmniToken technology, and supports transacting eCommerce and mobile payments against the same MercuryPay account.
It combines a direct In-App Apple Pay integration, accessing an OmniToken via Vantiv’s eCommerce eProtect service, and all of the back-end processing and settlement features that MercuryPay developers are already familiar with.
Below is a diagram of how these pieces fit together.
- The developer creates an iOS app using Apple's PassKit Framework. When the consumer uses the app to pay for something online, the iOS mobile app retrieves a PKPaymentToken from Apple and POSTs the PKPaymentToken to the Vantiv eProtect service.
- Vantiv eProtect converts the token from the mobile app into an eProtect token referred to as a Registration ID (aka payPageRegistrationId or low-value token). This registration ID is valid for 24 hours. Format: 19 digits, MOD 10+1.
- Note to readers: Developers using eProtect with the eCommerce platform, or consulting the eCommerce documentation, will be aware that eProtect by default when interacting with Vantiv's Litle eCommerce vault returns a cryptogram that does not adhere to the 19 digit format. This is a function of how the eProtect account is setup. eProtect accounts will need to be setup to interact with Vantiv's core vault rather than the Litle vault. eProtect LVTs that work with MercuryPay will be 19 digits.
- The transaction is processed using a MercuryPay tokenized transaction request, which contains one additional field called TokenType. In this case the value is "RegistrationID". The RecordNo field contains the Registration ID (low-value token) returned by eProtect. Here is an example:
The RegistrationID is used to flag MercuryPay servers that an OmniToken should to be returned in the transaction response.
- The transaction request is submitted to the back-end networks for authorization processing as usual.
- The transaction response includes the new OmniToken, which is returned in the RecordNo field to the application. The OmniToken can be stored in a local database and used for subsequent MercuryPay transactions such as Void or Adjust.
Using Apple Pay with eProtect
Your first step is to create your iOS app and integrate to Apple Pay using Apple's PassKit Framework. Apple Pay generates a PKPaymentToken when an iOS application requests payment data from the Apple wallet, as illustrated below:
- When the consumer selects the Apple Pay option on your iOS app, your app uses the Apple PassKit Framework to request payment data from Apple Pay.
- After the consumer approves the Payment Sheet (using Touch ID), Apple receives a call from your app and creates a PKPaymentToken using your public key. The PKPaymentToken includes a network (card brand) payment token and a cryptogram.
- Apple Pay returns the Apple PKPaymentToken to your app. The PKPaymentToken is used to obtain a Registration ID or low-value token from eProtect.
For more information on the Apple Pay PKPayment Token, please refer to: https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html
For more information about using Apple Pay with eProtect, please see Vantiv eCommerce Apple Pay Solution. (Note that this documentation assumes you are integrating with Vantiv's eCommerce platform via LitleXML, but to interface with MercuryPay you will be using the MercuryPay REST or SOAP APIs.
Before you can proceed with building and testing an integration, please make sure you have reviewed or have access to the resources below:
- Ensure that you have reviewed the Apple Pay API overview on the Apple Pay Developer Website.
- Ensure that you have test credentials to use the MercuryPay SOAP or REST API (your integration consultant can help you obtain these)
- Ensure that you have reviewed the Vantiv eProtect documentation
- Ensure that you have test credentials to work with the Vantiv eProtect service. Your integration consultant can help you obtain these as well. You will need to make it clear to your integration consultant that you are using OmniTokens so they can configure your eProtect account appropriately.
- You will additionally need a Certificate Signing Request (CSR) from Vantiv as explained below as well as public/private keys provided by Apple.
- Vantiv will provide you with a Certificate Signing Request (CSR), which you must submit to Apple. Apple will return the certificate, containing your public/private encryption keys, to you. Provide this information to your Implementation Consultant.
- Apple uses the public key to create the PKPaymentToken.
- Vantiv stores the PKPaymentToken received from the iOS app in our vault using eProtect. Vantiv uses the keys you provide to decrypt the PKPaymentToken on your behalf.
- Your consultant will create a test account for Vantiv's "pre-live environment" eProtect service. The CSR will be uploaded to your test account, which finalizes your configuration.
- Create an iOS app using the Apple Pay PassKit Framework. Refer to https://developer.apple.com/library/prerelease/content/ApplePay_Guide/index.html#//apple_ref/doc/uid/TP40014764-CH1-SW1
- Integrate to the eProtect Mobile API as described below. Please refer to the Vantiv Enterprise eProtect Integration Guide, Section 2.3: Integrating Mobile API into your Mobile Application for details on integrating to the eProtect Mobile API.
Calling eProtect from your iOS application
On receipt of a PKPaymentToken, your native iOS application will need to send the PKPaymentToken to Vantiv's eProtect server via an HTTPS POST in return for a payPageRegistrationID (referred to as the RegistrationId on the MercuryPay platform). The "Vantiv Mobile API for Apple Pay" is used for this purpose.
It is up to the iOS developer to construct the HTTPS POST. The Apple Pay specific fields that need to be provided in the POST are detailed in the table below.
Payment data dictionary, Base64 encoded as a string. Encrypted Payment data.
Detached PKCS #7 signature, Base64 encoded as string. Signature of the payment and header data.
|applepay.version||Version information about the payment token.|
SHA-256 hash, hex encoded as a string. Hash of the applicationData property of the original PKPaymentRequest.
X.509 encoded key bytes, Base64 encoded as a string. Ephemeral public key bytes.
SHA-256 hash, Base64 encoded as a string. Hash of the X.509 encoded public key bytes of the merchant's certificate.
Hex identifier, as a string. Transaction identifier, generated on the device.
An example cURL script shows how these fields above are posted to the eProtect endpoint (in this example Vantiv's pre-live eProtect environment). You will need the paypageId from Vantiv to call the eProtect server, included in your eProtect credentials.
Note that in addition to the Apple specific parameters above, parameters specific to Vantiv eCommerce need to be posted as well to make sure that Vantiv can identify and report on the transaction. These include the paypageId, the reportGroup, the orderId and the transaction Id.
These variables are defined in the LitleXML Reference Guide.
curl --verbose -H "Content-Type: application/x-www-form-urlencoded" -H "Host:MerchantApp" -H "User-Agent:Litle/1.0 CFNetwork/459 Darwin/10.0.0.d3" -d"paypageId=a2y4o6m8k0 &reportGroup=*merchant1500&orderId=PValid &id=1234 &applepay.data=<redacted-PKPayment token goes here> &applepay.version=EC_v1 &applepay.header.applicationData=496461ea64b50527d2d792df7c38f301300085dd463e347453ae72debf6f4d14 &applepay.header.ephemeralPublicKey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEarp8xOhLX9QliUPS9c54i3cqEfrJD37NG75ieNxncOeFLkjCk%2FBn3jVxHlecRwYqe%2BAWQxZBtDyewaZcmWz5lg%3%3D &applepay.header.publicKeyHash=zoV5b2%2BmqnMIxU9avTeqWxc7OW3fnKXFxyhY0cyRixU%3D &applepay.header.transactionId=23e26bd8741fea9e7a4d78a69f4255b315d39ec14233d6f1b32223d1999fb99f" https://request-prelive.np-securepaypage-litle.com/LitlePayPage/paypage
Variables returned to your iOS client in response to the POST to the eProtect servers are listed below:
|paypageRegistrationId||The temporary identifier used to facilitate the mapping of a token to a card number. This is referred to as the low-value token.|
|reportGroup||(Mirrored back from the request) The LitleXML required attribute that defines under which merchant sub-group this transaction will be displayed in iQ Reporting and Analytics.|
|orderId||(Mirrored back from the request) The merchant-assigned unique value representing the order in your system.|
|id||(Mirrored back from the request) The LitleXML required attribute that assigned by the presenter and mirrored back in the response.|
|litleTxnId||The automatically-assigned unique transaction identifier.|
|firstSix||(Mirrored back from the request) The first six digits of the credit card number.|
|lastFour||(Mirrored back from the request) The last four digits of the credit card number.|
Relay payment details from iOS to the merchant server
At this point, the iOS application will have received the information above required to process a payment transaction. Normally, calls to Vantiv's eCommerce platform are made from the merchant server rather than the iOS client since you will want to update log files and interface to inventory or order management or other systems. You will want to send the parameters received above in response to the eProtect POST along with other details about the transaction to the merchant server.
Choosing the OmniToken Format
The key to enabling Vantiv’s In-App Apple Pay integration with MercuryPay is the generation and use of an OmniToken. Your integration consultant will help you choose the right OmniToken format.
OmniTokens offer a shorter “format-preserved” reference to the cardholder’s credit card number with the actual card data being stored in Vantiv’s secure vault.
For MercuryPay integrations, the OmniToken is used in place of MToken (RecordNo). One additional tag, <TokenType> is used in the transaction request.
OmniTokens generated over the eProtect platform come in several different formats. When using them for MercuryPay, the MOD10+1 formats are preferable as they can be used to distinguish whether it is a token or actual credit card number. We recommend using either of the two formats below:
- Format T: Informative A1. Duplicates the length of the original PAN and preserves the first-six and last-four of the PAN. For example, if the original PAN is 14 characters long, the OmniToken will be 14 characters.
- Format D: Minimum 16A 1. Length is 16 if the original PAN is 16 characters or less, but can be up to 19 characters if the original PAN is that length. For example, if the original PAN is 14 digits long, the OmniToken will be 16 characters; if the original PAN is 19 characters, the OmniToken will be 19 characters.
Processing the In-App Apple Pay payment with Mercury Pay
Once your application has the OmniToken, the procedure for processing the payment with Vantiv's MercuryPay is the same whether you are using Apple Pay In-App or Apple Pay on the web.
Please skip to Processing Apple Pay Transactions through MercuryPay for details on how to construct a payment authorization on MercuryPay using the low-value token (RegistrationID) to perform an authorization and retrieve the OmniToken.