MercuryPay RESTful eCommerce Transactions

Document created by matthew.milner on May 10, 2016Last modified by matthew.milner on Jun 1, 2016
Version 4Show Document
  • View in full screen mode

Through our eCommerce RESTful API, developers can easily post payments in minutes. Below is the information a developer needs to begin posting transactions through their shopping cart. All requests should be sent to our Development Server. For code samples, visit our GitHub repository.

 

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

CERTIFICATION

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 MercuryPay

  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 in this document

The transaction samples provided in this document use the following convention:

Items in bold, red are required fields.

Items in grey are optional fields.

Items in bold, green are used in subsequent transactions.

 

Credit Transactions

Credit card information (card number and expiration date) can be sent by manual entry (keyed).

 

/Credit/Sale

A Credit Sale is used to process a credit card purchase (VISA, MasterCard, American Express, Discover, Carte Blanche, Diner’s Club, JCB or Other) in one step.

 

Step 1: Initial Token Request

Resource URL

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

 

Request

Add Address, Zip and CVVData for additional security when processing eCommerce transactions.

 

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Purchase":"1.00", 
"Frequency":"OneTime", 
"RecordNo":"RecordNumberRequested", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
"AcctNo":"4003000123456781", 
"ExpDate":"0517", 
"Address":"4 Corporate Square"; 
"Zip":"30329"; 
"CVVData":"880"; 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "Sale", 
"AuthCode": "08704A", 
"CaptureStatus": "Captured", 
"RefNo": "1002", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aAb312256069480098c1234d e000lA ", 
"RecordNo": "dg7MxDgG8ghU436R9uK6wEkLfqnZS4i6dNReolcrBociEgUQBSIQAxGl", 
"ProcessData": "|00|210100200000", 
"CVVResult"M"; 
"AVSResult":"A"; 
}

 

/Credit/SaleByRecordNo

Step 2:  Subsequent Use of the Token

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/SaleByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Purchase":"1.00", 
"Frequency":"OneTime", 
"RecordNo":"dg7MxDgG8ghU436R9uK6wEkLfqnZS4i6dNReolcrBociEgUQBSIQAxGl", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "Sale", 
"AuthCode": "08704A", 
"CaptureStatus": "Captured", 
"RefNo": "1002", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aAb312256069480098c1234d e000lA ", 
"RecordNo": "FIp35N1naUV42QRgdZXXwQP+EaX0da/UTeAPz/OW/E4iEgUQBSIQAxH1", 
"ProcessData": "|00|210100200000", 
}

 

/Credit/ZeroAuth

The ZeroAuth transaction enables merchants to validate a credit card without charging an amount to the cardholder’s account. It can also be used to request a token.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/ZeroAuth

 

Request: 

Substitute the Track2 data with the hand-keyed AcctNo and ExpDate as follows, and add Address, Zip and CVVData:

 

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Frequency":"OneTime", 
"RecordNo":"RecordNumberRequested", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
"AcctNo":"4003000123456781", 
"ExpDate":"0517", 
"Address":"4 Corporate Square"; 
"Zip":"30329"; 
"CVVData":"880"; 
} 

 

Response: 

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "ZeroAuth", 
"AuthCode": "08704A", 
"CaptureStatus": "Captured", 
"RefNo": "1002", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aAb312256069480098c1234d e000lA ", 
"RecordNo": "dg7MxDgG8ghU436R9uK6wEkLfqnZS4i6dNReolcrBociEgUQBSIQAxGl", 
"ProcessData": "|00|210100200000", 
"CVVResult"M"; 
"AVSResult":"A"; 
} 

 

Credit Reversal

 

Reversals are neither a Transaction Type nor a specific XML TranCode, but refer to a practice within the card processing industry of communicating directly with the card Issuing bank in order to reverse the transaction and release the held funds back into the cardholder’s account. This is the preferred method for cancelling a transaction within the live batch. Reversals generally take less time (from 2 to 72 hours) to be removed from the cardholder’s banking statement. Reversals may be used to reverse an existing Credit Sale, PreAuthCapture and PreAuth.  Follow the steps below to process a Reversal request:

 

  1. The request must include all the required TranCode data elements of a standard VoidSale (AcctNo, Exp Date, InvoiceNo, RefNo, AuthCode, Purchase and Memo).
  2. Two additional data elements from the original transaction response are required: AcqRefData and ProcessData. This sends the request to the Issuing bank.
  3. Finally, confirm that a CmdStatus=Approved and TextResponse=REVERSED message is returned; if it is not returned a standard VoidSale should be immediately sent without the AcqRefData and ProcessData elements.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/VoidSaleByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1040", 
"Memo":"MPS Example JSON v1.0", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"AuthCode":"06187A", 
"Frequency":"OneTime", 
"RecordNo":"dg7MxDgG8ghU436R9uK6wEkLfqnZS4i6dNReolcrBociEgUQBSIQAxGl", 
“AcqRefData”:”aEb014321193006580cABCId5e00fJlA M000005” 
“ProcessData”:”00|201000200000” 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "REVERSED", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "VoidSale", 
"AuthCode": "VI1234", 
"RefNo": "0001", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aY", 
"RecordNo": "FIp35N1naUV42QRgdZXXwQP+EaX0da/UTeAPz/OW/E4iEgUQBSIQAxH1", 
"ProcessData": "|A4|210100200000", 
} 

 

/Credit/VoidSaleByRecordNo

 

A VoidSale cancels a previously completed Credit Sale, PreAuthCapture or Return transaction that is logged with a reference number in the merchant’s current open batch.  A VoidSale communicates with the processor and may take several business days before the sale is removed from the cardholder’s bank account. VoidSales require the reference number (RefNo) and AuthCode from the original transaction, as well as InvoiceNo, the full card number, expiration date and authorized purchase amount.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/VoidSaleByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1040", 
"Memo":"MPS Example JSON v1.0", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"AuthCode":"06187A", 
"Frequency":"OneTime", 
"RecordNo":"dg7MxDgG8ghU436R9uK6wEkLfqnZS4i6dNReolcrBociEgUQBSIQAxGl", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "VoidSale", 
"AuthCode": "VI1234", 
"RefNo": "0001", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aY", 
"RecordNo": "FIp35N1naUV42QRgdZXXwQP+EaX0da/UTeAPz/OW/E4iEgUQBSIQAxH1", 
"ProcessData": "|A4|210100200000", 
}

 

/Credit/Return

 

A Return is the opposite of a Sale. It is an independent, non-referenced transaction used to credit a cardholder’s account. DO NOT USE a Return to refund a transaction in the current open batch.

 

Step 1: Initial Token Request

 

Resource URL

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

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Frequency":"OneTime", 
"RecordNo":"RecordNumberRequested", 
"AcctNo":"4003000123456781", 
"ExpDate":"0517", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "Return", 
"AuthCode": "029720", 
"CaptureStatus": "Captured", 
"RefNo": "1001", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"RecordNo": "HaCmUGIs9keoV2TMH7Usv29goaENjFrzanDS1yt+CYUiEgUQBSIQAxHa", 
"ProcessData": "|20|210100200000", 
}

 

/Credit/ReturnByRecordNo

 

Step 2: Subsequent Use of the Token

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/ReturnByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Frequency":"OneTime", 
"RecordNo":"HaCmUGIs9keoV2TMH7Usv29goaENjFrzanDS1yt+CYUiEgUQBSIQAxHa", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "Return", 
"AuthCode": "029720", 
"CaptureStatus": "Captured", 
"RefNo": "1001", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"RecordNo": "FIp35N1naUV42QRgdZXXwQP+EaX0da/UTeAPz/OW/E4iEgUQBSIQAxH1", 
"ProcessData": "|20|210100200000", 
}

 

/Credit/VoidReturnByRecordNo

 

Once captured, use VoidReturn to void original Return transactions.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/VoidReturnByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1001", 
"Memo":"MPS Example JSON v1.0", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"AuthCode":"029720", 
"Frequency":"OneTime", 
"RecordNo":"HaCmUGIs9keoV2TMH7Usv29goaENjFrzanDS1yt+CYUiEgUQBSIQAxHa", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "VoidReturn", 
"AuthCode": "VOIDED", 
"CaptureStatus": "Captured", 
"RefNo": "1001", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"RecordNo": "FIp35N1naUV42QRgdZXXwQP+EaX0da/UTeAPz/OW/E4iEgUQBSIQAxH1", 
"ProcessData": "|A4|210100200000", 
}

 

/Credit/PreAuth

 

This approach is used when the credit purchase occurs in two steps, authorization (PreAuth) and capture (PreAuthCapture). This is commonly used when the exact purchase amount isn’t known, but the transaction will be processed for payment later. eCommerce merchants commonly use it when their ship-date is more than 24 hours after the online order. The PreAuth is used to pre-authorize an estimated amount on a credit card. The transaction will be finalized using a subsequent PreAuthCapture, discussed in the next example.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/PreAuth

Step 1: Initial Token Request

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"AcctNo":"4003000123456781", 
"ExpDate":"0517", 
"Address":"4 Corporate Square"; 
"Zip":"30329"; 
"CVVData":"880"; 
"Frequency":"OneTime", 
"RecordNo":"RecordNumberRequested", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"Authorize":"1.00", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
ResponseOrigin: "Processor", 
DSIXReturnCode: "000000", 
CmdStatus: "Approved", 
TextResponse: "AP", 
UserTraceData: "", 
MerchantID: "395347306", 
AcctNo: "400300XXXXXX6781", 
ExpDate: "XXXX", 
CardType: "VISA", 
TranCode: "PreAuth", 
AuthCode: "05764A", 
InvoiceNo: "1", 
OperatorID: "MPS Operator", 
Memo: "MPS Example JSON v1.0", 
Purchase: "1.00", 
Authorize: "1.00", 
AcqRefData: "aAb312256069480098c1234d e000lA ", 
RecordNo: "NT3ooUkj3eLBVRy6tPK6lUFDJHch/kgcXkeZ0ETfFk4iEgUQBSIQAxIa", 
ProcessData: "|14|210100200000", 
"CVVResult"M"; 
"AVSResult":"A"; 
}

 

/Credit/PreAuthByRecordNo

 

Step 2: Process the Transaction

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Credit/PreAuthByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Frequency":"OneTime", 
"RecordNo":"NT3ooUkj3eLBVRy6tPK6lUFDJHch/kgcXkeZ0ETfFk4iEgUQBSIQAxIa", 
"Name":"MPS TEST", 
"Purchase":"1.00", 
"Authorize":"1.00", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
}   

 

Response

{ 
ResponseOrigin: "Processor", 
DSIXReturnCode: "000000", 
CmdStatus: "Approved", 
TextResponse: "AP", 
UserTraceData: "", 
MerchantID: "395347306", 
AcctNo: "400300XXXXXX6781", 
ExpDate: "XXXX", 
CardType: "VISA", 
TranCode: "PreAuth", 
AuthCode: "05764A", 
InvoiceNo: "1", 
OperatorID: "MPS Operator", 
Memo: "MPS Example JSON v1.0", 
Purchase: "1.00", 
Authorize: "1.00", 
AcqRefData: "aAb312256069480098c1234d e000lA ", 
RecordNo: "Q8in68Zg8WljfFFddk8loqxcyAD2vMGbqCxQheLrxX8iEgUQBSIQAxJC", 
ProcessData: "|14|210100200000", 
}

 

/Credit/PreAuthCaptureByRecordNo

 

PreAuthCapture is used to finalize a previous PreAuth transaction so that settlement can occur.

 

Resource URL

 

POST https://w1.mercurycert.net/PaymentsAPI/Credit/PreAuthCaptureByRecordNo

 

Request

{ 
"InvoiceNo":"1", 
"RefNo":"1", 
"Memo":"MPS Example JSON v1.0", 
"Frequency":"OneTime", 
"RecordNo":" NT3ooUkj3eLBVRy6tPK6lUFDJHch/kgcXkeZ0ETfFk4iEgUQBSIQAxIa", 
"Purchase":"1.00", 
"Authorize":"1.00", 
"AuthCode":"05764A", 
"AcqRefData":"aAb312256069480098c1234d e000lA", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Approved", 
"TextResponse": "AP", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"AcctNo": "400300XXXXXX6781", 
"ExpDate": "XXXX", 
"CardType": "VISA", 
"TranCode": "PreAuthCapture", 
"AuthCode": "05764A", 
"CaptureStatus": "Captured", 
"RefNo": "1002", 
"InvoiceNo": "1", 
"OperatorID": "MPS Operator", 
"Memo": "MPS Example JSON v1.0", 
"Purchase": "1.00", 
"Authorize": "1.00", 
"AcqRefData": "aAb312256069480098c1234d e000lA", 
"RecordNo": "WVTncMTApjnzoIjCVT8NCCAyMxGihsoV+jwAPxiW1T4iEgUQBSIQAxJR", 
"ProcessData": "|15|210100200000", 
}
2 people found this helpful

Attachments

    Outcomes