MercuryPay - Getting Started with MToken

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.

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.

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:

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.