Processing Apple Pay transactions through the MercuryPay Platform

Document created by gjsissons on Jul 20, 2016Last modified by gjsissons on Nov 3, 2016
Version 13Show Document
  • View in full screen mode

For ISV’s already integrated with the MercuryPay platform wishing to add support for Apple Pay in-app or web payments, the  final step in the OmniChannel for IP integration is building the transaction request and sending it to MercuryPay.


The transaction payload uses the same XML request format that MercuryPay developers are already familiar with.


There are a few minor differences to “flag” the transaction as OmniChannel, which will trigger the creation of an OmniToken.


As with any <RecordNo> enabled transactions, it is important that your merchants are setup for tokenization.


For ISV’s who are interested in using OmiChannel for Integrated Payments and do not have an integration to the MercuryPay platform, see Getting Started with MercuryPay for an overview.


Below is an example of the XML transaction request/response. In this scenario, assume that your Apple Pay app or website has sent a request to eProtect initiating the transaction flow and now you are ready to process the payment through MercuryPay.


The example illustrates a simple sale sent as a SaleByRecordNo and using a RegistrationID token in the request.


Notice that the request is almost identical to a standard MToken transaction request, using <Frequency> (one time or recurring) and <RecordNo> (actual token).


There is one new tag called <TokenType>, which is used to flag what type of token is included in the <RecordNo> field, allowing the transaction to be  routed correctly. TokenType can contain one of three values:



  • RegistrationID: This value indicates the <RecordNo> contains a RegistrationID and is requesting an OmniToken
  • OmniToken: Indicates that the <RecordNo> contains an OmniToken
  • MToken: indicates that <RecordNo> contains an MToken and will follow the standard MToken process






<?xml version="1.0"?>
  <TranCode>SaleByRecordNo</TranCode>  <!--note the TranCode is SaleByRecordNo-->
  <Frequency>OneTime</Frequency> <!--value can be either OneTime or Recurring-->
  <TokenType>RegistrationID</TokenType> <!--note the additional TokenType tag -->
  <RecordNo>6462804160238318943</RecordNo> <!-- this is the RegistrationID -->
  <Memo>Your Application Name</Memo>
  <Address>150 Mercury Village</Address>


Note:  The TranCode is sent as SaleByRecordNo because the transaction is using the RegistrationID, which is a token.





  <Memo>XYZ Co Test</Memo>
  <RecordNo>4003003446996781</RecordNo> <!--this is the OmniToken-->




The above response illustrates a successful transaction. The value within the RecordNo is the OmniToken. The OmniToken can be used to process subsequent transactions, listed below:

AdjustByRecordNoChanges the Amount value for a transaction captured in the current open batch
ReturnByRecordNoRefunds a sale that is in a closed batch. This is an independent transaction that does not need to refer to the original sale.
VoidReturnByRecordNoCancels a return
VoidSaleByRecordNoCancels a sale



See MercuryPay MToken  and  MToken Error Messages for more information about MercuryPay token transactions.


Integration Methods


MercuryPay provides a standard transaction payload format that is derived from Datacap ePay technologies. There are minor differences in how the Datacap components are accessed, which forms the basis of MercuryPay’s two primary integration methods described below. In both cases the Datacap ePay technology is used to validate and pass XML requests to MercuryPay’s processing servers.

  • SOAP. The XML transaction requests are inserted into a Simple Object Access Protocol (SOAP) envelope. This SOAP-wrapped XML is then used to make a  transaction call to MercuryPay’s Web Service servers. MercuryPay unwraps the transaction, extracts the XML payload, calls our client interface and then routes the request to our internal processing servers for authorization. The transaction XML response is then re-wrapped in a SOAP envelope and returned to the POS. The SOAP method supports batch and transaction detail method calls.  Refer to the Platform Integration Guide Supplement: SOAP Method for implementation details.
  • REST. MercuryPay’s RESTful API, strictly speaking, is not a pure REST solution. It is a simplified and highly robust hybrid of JSON using remote procedure calls (RPC). MercuryPay developed this integration method in response to the demand from mobile developers, as an alternative to SOAP. JSON RPC is a lightweight data-interchange format that is simpler to implement than SOAP.

       Refer to the Platform Integration Guide Supplement: PaymentsAPI—JSON Remote Procedure Calls for implementation details.


Please refer to the MercuryPay Platform Integration Guide for complete information about the MercuryPay platform.