MercuryPay RESTful Batch Functions

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

End-of-Day Batch Closing and Settlement

 

In addition to managing payment modules, eCommerce solutions may also manage the end-of-day batch closing and settlement procedures. Our eCommerce RESTful API offers two varieties of capture and close methods to meet the needs of today’s complex payment systems.

 

Time-Initiated Batch Close 

 

This is also referred to as “auto-settle.” Vantiv Integrated Payments initiates the batch settlement.

 

Time-initiated batch close is an auto-settle function whereby all captured transactions are settled in one batch at 4:00 AM Eastern Standard Time (EST). It provides standard two-day funding. Other close times may be available based on sponsoring bank arrangements, end-of-day closing time and funding times needed.

 

  • Time-initiated avoids the common issue of merchants forgetting to close their batch, or having problems matching up their totals and number of transactions.
  • The developer does not need to write code to support a BatchClose transaction.
  • The 4:00 AM EST may not be optimal for some eCommerce merchants.

 

Merchant-Initiated Batch Close

 

Merchant-initiated means there is a local, merchant-facing BatchClose command from the payment application or an auto generated BatchClose from the payment server, which initiates the settlement process.

 

Merchants must close their batch within 24 hours of the original authorization or they will face downgrades (higher transaction rates). This is because authorization codes increasingly lose their interchange authenticity over time and inherently carry higher risk. If a batch remains open too long, there is built-in protection to stop accepting additional capture transactions and return the message, “MUST BALANCE NOW” or “USE DUP THEN BAL.”

 

  • The maximum size for a merchant-initiated batch is approximately 4500 transactions. It is important to avoid hitting this threshold. If it is reached, the merchant will receive a MUST BALANCE NOW message. Processing will be temporarily interrupted until the batch is successfully closed.

 

The merchant-initiated batch close uses a two-step set of Admin transactions requests: BatchSummary and BatchClose.

 

BatchSummary and BatchClose are meant to offer a quick, snapshot comparison of batch item counts and totals between the merchant batch file stored on the MercuryPay servers and their local totals on the payment application. The steps and XML examples below illustrate the logic behind this sequence.

 

BatchSummary 

 

BatchSummary is used to get a summary of the information in the batch: totals and counts by card type.

 

[Symbol] Note A BatchSummary request must be performed just prior to a BatchClose request and all relevant response fields in the BatchSummary should be supplied in the BatchClose if available. The Debit data elements must be sent in the BatchClose even when PIN debit is not supported.

 

Resource URL

 

POST https://w1.mercurycert.net/PaymentsAPI/Admin/BatchSummary

 

Request

{ 
"Memo":"MPS Example JSON v1.0", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Success", 
"TextResponse": "OK", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"OperatorID": "MPS Operator", 
"BatchNo": "0221", 
"BatchItemCount": "3", 
"NetBatchTotal": "3.20", 
"CreditPurchaseCount": "3", 
"CreditPurchaseAmount": "3.20", 
"CreditReturnCount": "0", 
"CreditReturnAmount": "0.00", 
"DebitPurchaseCount": "0", 
"DebitPurchaseAmount": "0.00", 
"DebitReturnCount": "0", 
"DebitReturnAmount": "0.00", 
} 

 

BatchClose is used to close the currently open batch.

[Symbol] Note  All values in the BatchClose must match those returned from the BatchSummary response. The Debit data elements must be sent in the BatchClose even when PIN debit is not supported.

 

Resource URL

POST https://w1.mercurycert.net/PaymentsAPI/Admin/BatchClose

 

Request

{ 
"Memo":"MPS Example JSON v1.0", 
"BatchNo":"0221", 
"BatchItemCount":"3", 
"NetBatchTotal":"3.20", 
"CreditPurchaseCount":"3", 
"CreditPurchaseAmount":"3.20", 
"CreditReturnCount":"0", 
"CreditReturnAmount":"0.00", 
"DebitPurchaseCount":"0", 
"DebitPurchaseAmount":"0.00", 
"DebitReturnCount":"0", 
"DebitReturnAmount":"0.00", 
"TerminalName":"MPS Terminal", 
"ShiftID":"MPS Shift", 
"OperatorID":"MPS Operator" 
} 

 

Response

{ 
"ResponseOrigin": "Processor", 
"DSIXReturnCode": "000000", 
"CmdStatus": "Success", 
"TextResponse": "OK", 
"UserTraceData": "", 
"MerchantID": "395347306", 
"OperatorID": "MPS Operator", 
"BatchNo": "0221", 
"BatchItemCount": "3", 
"NetBatchTotal": "3.20", 
"CreditPurchaseCount": "3", 
"CreditPurchaseAmount": "3.20", 
"CreditReturnCount": "0", 
"CreditReturnAmount": "0.00", 
"DebitPurchaseCount": "0", 
"DebitPurchaseAmount": "0.00", 
"DebitReturnCount": "0", 
"DebitReturnAmount": "0.00", 
"ControlNo": "0221", 
}

Attachments

    Outcomes