MercuryPay MToken

Document created by chadb on May 10, 2016Last modified by Chris Jennings on Dec 15, 2016
Version 4Show Document
  • View in full screen mode

When requested by the POS, a token is generated and returned with the transaction authorization approval response. The token can then be used in place of the cardholder account number to perform subsequent transactions if required, it can be stored safely for card-on-file or recurring billing programs.

 

Tokens are unique, dynamically-generated reference numbers. They are used to replace sensitive card data for security purposes. It has become popular as a means of reducing the risk, cost, and complexity of credit card processing.  MercuryPay MToken’s are uniquely generated per transaction and is returned in the transaction response, in a standard Base64 format.

 

Merchant account numbers (MID) are set up to reflect MToken capability on both MercuryPay and the payment application.

 

Initial Token Request

Tokens are only generated “by request”. This is done using a standard XML transaction request with two additional tags: <RecordNo> and <Frequency>. A token frequency may either be for OneTime use or for Recurring.

 

A OneTime token expires six months from the date the token record is generated. With each subsequent use a new token is generated and returned, adding an additional six months. One-time tokens are recommended for all daily use transactions or for “card-on-file” supported systems.

 

A Recurring token expires 24 months from the date the token record is generated. With each subsequent use a new token is generated and returned, adding an additional 24 months. Recurring tokens are used for environments where weekly, monthly or annual subscription billing is implemented.

 

 

Element

 

Req

 

Min

 

Max

 

Type

 

Description

 

Transaction: RecordNo

 

Y

 

1

 

100

 

AN

 

Used on the initial request to generate a token using ‘RecordNumberRequested.  Use the actual token returned from MercuryPayin subsequent “ByRecordNo” requests

 

Transaction: Frequency

 

Y

 

7

 

20

 

AN

 

Type of Token requested: 'OneTime'or 'Recurring'

 

Clear Text Card Data XML Request

<?xml version="1.0"?> 
<TStream> 
<Transaction> 
  <MerchantID>023358150511666</MerchantID>  <!--specific token enabled MID --> 
<OperatorID>Test</OperatorID> 
<LaneID>02</LaneID> <!--required for multi-terminal environments--> 
<TranType>Credit</TranType> 
<PartialAuth>Allow</PartialAuth> 
<TranCode>Sale</TranCode> 
<InvoiceNo>20</InvoiceNo> 
<RefNo>20</RefNo> 
<Memo>Product v1.1</Memo> 
<RecordNo>RecordNumberRequested</RecordNo> <!--tag used to request a token on response--> 
<Frequency>OneTime</Frequency> <!--indicates one-time token--> 
<Account> 
<Track2>4003000123456781=13055025432198712345</Track2> 
</Account> 
<Amount> 
<Purchase>2.25</Purchase> 
</Amount> 
</Transaction> 
</TStream> 

 

Note: Frequency values must stay consistent in all subsequent used of MToken requests. Inconsistent use of Frequency will cause the subsequent transaction request to fail with the following error: Error # 004119- Token Service Unavailable. – 200 Response With Status: Failure Message: Parse token failure.

 

Initial Token Response

MercuryPay processes the transaction normally, and then generates a RecordNo based on the request criteria, which replaces the account number and expiration date. This RecordNo is then passed back within the authorization response. Per business need, store the token “as-is” for future use.

 

 

Element

 

Req

 

Min

 

Max

 

Type

 

Description

 

Response: RecordNo

 

Y

 

48

 

100

 

AN

 

Token record returned from Mercury

 

XML Response 

<?xml version="1.0" ?> 
<RStream> 
<CmdResponse> 
<ResponseOrigin>Processor</ResponseOrigin> 
<DSIXReturnCode>000000</DSIXReturnCode> 
<CmdStatus>Approved</CmdStatus> 
<TextResponse>AP</TextResponse> 
</CmdResponse> 
<TranResponse> 
<MerchantID>023358150511666</MerchantID> 
<AcctNo>400300XXXXXX6781</AcctNo> <!--Note truncated Account number--> 
<ExpDate>0119</ExpDate> 
<CardType>VISA</CardType> 
<TranCode>Sale</TranCode> 
<AuthCode>000027</AuthCode> 
<CaptureStatus>Captured</CaptureStatus> 
<RefNo>0003</RefNo> 
<InvoiceNo>0020</InvoiceNo> 
<OperatorID>Test</OperatorID> 
<Memo>Product v1.1</Memo> 
<Amount> 
<Purchase>2.25</Purchase> 
<Authorize>2.25</Authorize> 
</Amount> 
<AcqRefData>aEb000140567810225c0225d5e00</AcqRefData> 
<RecordNo>BuFzLtekgFrTsiCOxI59PCQUfZe32C3YYXgXuPuFU64yEAQQADIQAAIX      
        </RecordNo><!--typical token length is 48-53 char, but should be coded to 100--> 
<ProcessData>|00|210100201000</ProcessData> 
  </TranResponse> 
</RStream>  

 

Subsequent Token Use

As illustrated in the above examples, a Token will be passed back to the payment application on all credit TranCodes (Debit, EBT and Gift will not return a Token). The returned token is referred to as the “Record Number” (RecordNo) and all subsequent requests using a token will be submitted by adding ByRecordNo to the TranCode.

 

The following table lists the TranCodes for Token Requests and corresponding subsequent usage ByRecordNo TranCodes:

 

 

Credit TranCodesUsed to Request a Token

 

TranCodesfor Subsequent Use of Token

 

Adjust

 

AdjustByRecordNo

 

CardLookUp

 

NA

 

FSASale

 

FSASaleByRecordNo

 

PreAuth

 

PreAuthByRecordNo

 

PreAuthCapture

 

PreAuthCaptureByRecordNo

 

Return

 

ReturnByRecordNo

 

ReverseFSASale

 

ReverseFSASaleByRecordNo

 

Sale

 

SaleByRecordNo

 

VoidReturn

 

VoidReturnByRecordNo

 

VoidSale

 

VoidSaleByRecordNo

 

ZeroAuth

 

NA

 

When building a ByRecordNo XML request, use the appropriate ByRecordNo TranCode from the above table and replace the entire Account level tags with the actual token using the RecordNo tag. Note, too, that the Frequency must match the original requested token frequency.

 

Storing Tokens

  1. Only store a token record if there is a business need and if this information supports your targeted business/merchants.
  2. Build retention and expiration timelines for any stored token record. Note that because of truncated card expiration data returned in the token response, developers should, if needed, obtain the expiration date prior to processing the request.
  3. Always dispose of expired token records.
  4. Tokens are dynamically refreshed per use. A new token record will always be returned with each subsequent transaction. If storing token data, store only the most recent token record returned.

Attachments

    Outcomes