Vantiv StoreCard JSON Transactions 

Document created by chadb on May 10, 2016Last modified by chadb on Jun 1, 2016
Version 2Show Document
  • View in full screen mode

Vantiv’s RESTful (JSON RPC) method uses JSON formatted requests and responses for transaction processing.

 

Setup

JSON formatted requests and responses are used over HTTPS for transaction processing.

 

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 transactions are posted to https://w1.mercurycert.net/PaymentsAPI (for development and testing) 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

 

Code Samples: Conventions used

The code samples  that follow these conventions:

  • Items in bold, red are required fields.
  • Items in grey are optional fields.
  • Items in bold, green are used in subsequent transactions.

 

RESTful Payload Examples

 

/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