StoreCard REST Transactions on MercuryPay

Document created by chadb on May 10, 2016Last modified by Chris Jennings on Sep 12, 2017
Version 7Show Document
  • View in full screen mode

Setup

JSON formatted requests and responses are used over HTTPS for transaction processing on the MercuryPay Interface.

 

Hosts

Production Server

 

 

PRIMARY

 

https://w1.mercurypay.com/PaymentsAPI/

 

Production Server

 

BACKUP

 

https://w2.mercurypay.com/PaymentsAPI/

 

Development Server

 

PRIMARY

 

https://w1.mercurycert.net/PaymentsAPI/

 

Authentication

Authentication occurs via HTTP Basic Auth using an HTTP authorization header.

Username: existing MerchantID

Password: created and stored by Vantiv

  1. Create string of [username]:[password]
  2. BASE64 encoded string
  3. Set Authorization header value to: “Basic [encoded string]”

 

Content-Type

Set Content-Type header value to: “application/json”

 

POSTS

All test transactions are posted to https://w1.mercurycert.net/PaymentsAPI followed by the transaction type at the end of the URL (referred to in this document as the Resource URL). For example, a credit sale would be: https://w1.mercurycert.net/PaymentsAPI/Credit/Sale

 

 

Example REST .CSharp Gift Sale Request

There is a common set of data elements used to build gift transaction payloads, regardless of how your code is implemented. This section describes these common features as XML-based pairs.

 

Step 1: Collect and format transaction information

Developers will need to collect and format transaction information utilizing an object model and set each parameter needed to process a transaction. The example below shows a gift sale transaction. The class object is then serialized to JSON and represented as a string variable.

 

jsonDict.Add("RefNo","1");
jsonDict.Add("InvoiceNo","1");
jsonDict.Add("Memo","test");
jsonDict.Add("Purchase","1.11");
jsonDict.Add("AcctNo","6050110010032766771");
jsonDict.Add("OperatorID","test");

var jsonData = new JavaScriptSerializer().Serialize(jsonDict);

 

 

Step 2: POST Request to StoreCard Platform

Using the .net libraries a web request is made to the gift server POSTing the JSON above. Note that you need a MerchantID and Password to perform the Basic Auth. All of the "plumbing" code is included in the DoGiftRequest method. The second parameter of this method appends to the base URL which is how you will switch transaction types. For example to send a Gift Issue command replace "Sale" with "Issue".

 

var response = GiftWebRequest.DoGiftRequest(jsonData, "Sale");

 

 

Step 3: Process and Display Response

After receiving the response deserialize the JSON string to a dynamic object, in this case a Dictionary and then parse the values into an object so it will be easier to work with. That object is then passed to the view for display purposes.

 

var paymentResponse = new PaymentResponse();

var giftResponse = new JavaScriptSerializer().Deserialize<dynamic>(json);
if(giftResponse.ContainsKey("ResponseOrigin")){ paymentResponse.ResponseOrigin = giftResponse["ResponseOrigin"];}
if(giftResponse.ContainsKey("DSIXReturnCode")) {paymentResponse.DSIXReturnCode = giftResponse["DSIXReturnCode"];}

 

 

 

Complete List of RESTful Payloads

 

/PrePaid/Issue

A PrePaid Issue is the first transaction processed on a new Gift card. The Issue activates the card, sets the initial card balance, and associates the card with the usage parameters on the gift server. Once a card is activated and put into use, it remains “issued” for the life of the card.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/Issue

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "Issue", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564643", 
  "AuthCode": "564643", 
  "Authorize": "1.00", 
  "Purchase": "1.00", 
  "Balance": "1.00" 
}

 

/PrePaid/VoidIssue

A PrePaid VoidIssue cancels the issuance of a card, returning the account balance to 0.00 and puts the card into a non-issued stat. VoidIssue is allowed only when there is no transaction history on the card since the original Issue transaction.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/VoidIssue

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"564643", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator", 
"AuthCode":"564643" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Voided", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "VoidIssue", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0365", 
  "RefNo": "564644", 
  "Authorize": "1.00", 
  "Purchase": "1.00", 
  "Balance": "0.00" 
} 

 

/PrePaid/Sale

 

A PrePaid Sale takes value off of the card, reducing the available balance by that purchase amount. Declines the transaction if there is insufficient balance.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/Sale

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
}

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "Sale", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564649", 
  "AuthCode": "564649", 
  "Authorize": "1.00", 
  "Purchase": "1.00", 
  "Balance": "4.28" 
} 

 

/PrePaid/VoidSale

A PrePaid VoidSale cancels a previously approved Sale.

Note  The VoidSale must specify the RefNo (reference number) and AuthCode (authorization code) returned in the originating transaction response, as well as the card number and original transaction amount.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/VoidSale

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"564649", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator", 
"AuthCode":"564649" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Voided", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "VoidSale", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564649", 
  "Balance": "5.28", 
  "Authorize": "1.00", 
  "Purchase": "1.00" 
} 

 

/PrePaid/NoNSFSale

A PrePaid NoNSFSale takes value off of the card, reducing the available balance by that purchase amount. If there is an insufficient account balance, the transaction will approve for the remaining balance on the card. This requires the POS to manage a “Balance Due” split-tender if there is an insufficient balance on the card to cover the total purchase amount.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/NoNSFSale

 

Request: Swipe

 

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "NoNSFSale", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564651", 
  "AuthCode": "564651", 
  "Authorize": "1.00", 
  "Purchase": "1.00", 
  "Balance": "4.28" 
} 

 

/PrePaid/Reload

A PrePaid Reload adds value to a card, increasing the balance. The default is two reloads per day, but this can be changed by request to a maximum of 10 reloads per day.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/Reload

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"20.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "Reload", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564662", 
  "AuthCode": "564662", 
  "Authorize": "20.00", 
  "Purchase": "20.00", 
  "Balance": "24.28" 
} 

 

/PrePaid/VoidReload

A PrePaid VoidReload cancels a previously approved Reload.

Note  The VoidReload must specify the RefNo (reference number) and AuthCode (authorization code) returned in the originating transaction response, as well as the card number and original transaction amount.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/VoidReload

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"564662", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"20.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator", 
"AuthCode":"564662" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Voided", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "VoidReload", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564662", 
  "Balance": "4.28", 
  "Authorize": "20.00", 
  "Purchase": "20.00" 
} 

 

/PrePaid/Return

A PrePaid Return adds value to a card, increasing the balance. This is typically used when merchandise is returned and the value is added to a Gift card in place of cash.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/Return

 

Request: Swipe

{ 
"InvoiceNo":"2", 
"RefNo":"2", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"20.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "Return", 
  "InvoiceNo": "2", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564699", 
  "AuthCode": "564699", 
  "Authorize": "1.00", 
  "Purchase": "1.00", 
  "Balance": "25.28" 
} 

 

/PrePaid/VoidReturn

A PrePaid VoidReturn cancels a previously approved Return.

Note  The VoidReturn must specify the RefNo (reference number) and AuthCode (authorization code) returned in the originating transaction response, as well as the card number and original transaction amount.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/VoidReturn

 

Request: Swipe

{ 
"InvoiceNo":"2", 
"RefNo":"564699", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"Purchase":"1.00", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator", 
"AuthCode":"564699" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Voided", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "VoidReturn", 
  "InvoiceNo": "2", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "RefNo": "564699", 
  "Balance": "24.28", 
  "Authorize": "1.00", 
  "Purchase": "1.00" 
} 

 

/PrePaid/Balance

A PrePaid Balance returns the remaining balance of a card.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/PrePaid/Balance

 

Request: Swipe

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"VANTIV Example JSON v1.0", 
"Track2":"7712950000000000353=250110118", 
"TerminalName":"VANTIV Terminal", 
"ShiftID":"VANTIV Shift", 
"OperatorID":"VANTIV Operator" 
} 

 

Request: Keyed (manual)

Substitute the Track2 data with the hand-keyed account number as follows:

"AcctNo":"7712950000000000353", 

 

Response

{ 
  "ResponseOrigin": "Processor", 
  "DSIXReturnCode": "000000", 
  "CmdStatus": "Approved", 
  "TextResponse": "Approved", 
  "UserTraceData": "", 
  "MerchantID": "595901", 
  "TranType": "PrePaid", 
  "TranCode": "Balance", 
  "InvoiceNo": "1", 
  "TerminalName": "VANTIV Terminal", 
  "OperatorID": "VANTIV Operator", 
  "AcctNo": "771295XXXXXXXXX0353", 
  "Balance": "24.28" 
} 

Attachments

    Outcomes