Chapter 6 – Batch Method | Nuvei Technologies

The purpose of the Batch method is to settle the Merchant’s credit card transactions at the end of the business day. When credit cards are integrated into the merchant’s business systems, the business type(s) that will be supported must be chosen. Most merchants will only process transactions using a single business type (for example, a merchant with a brick and mortar store will most likely process only retail transactions). However, some merchants may need to process using multiple business types. For example, the same merchant with the brick and mortar store may also have a mail-order business or an eCommerce website which may require additional merchant accounts.

Regardless of the business type(s) chosen, credit card processing can be broken down to a two-step process. When a credit card transaction (such as a Sale) is performed by the merchant, the customer‘s open to buy on their credit card account is reduced and the transaction is placed into what payment processors call a “batch.” A batch is defined as a collection of transactions that are approved but have not yet been resubmitted for end of day settlement. Before funds can be deposited into the merchant‘s bank account, a second step – a re- transmission often called a settlement - must occur.

Section 6.1 - Host based and Terminal based Processors link

Payment processors handle settlement two different ways: Host based and Terminal based. As a payments integrator, it is very important to understand the differences between the two. Based on which type of processor will be used by the merchant, certain tasks must be performed by the merchant to enable them to receive funds from their credit card transactions. These actions can be invoked by using the Batch Method.

The re-transmission process is called Batch Settlement or Batch Close. Terminal based processors have batches that are settled, and Host based processors have batches that are closed. Whether Host based or Terminal based, all credit card transactions in a batch have to be re-submitted to the processing company. The following describes the differences between host and terminal processors:

Terminal based – If the merchant is using a Terminal based processor, the payment device used with Nuvei stores the batch of transactions. With Terminal based processors, batch settlement must be done manually by the merchant, usually at the end of each business day.

Host based - With a Host based system, the batch is stored on the credit card processor's system, the Host. With a Host based system, merchants can be set up in one of two ways:

Auto (Time Initiated) Close – At a certain time during the day, the Host based system will scan its computer system. If a merchant has an open batch of transactions, the system will automatically close the batch. Based on the processor, the merchant can specify the time when the batch will be closed each day. If a merchant is set up for Auto Close with their Host based processor, there are no steps needed to initiate the batch close process.
Manual Close – Credit card transactions will sit in an open batch indefinitely. The merchant is responsible for indicating to the Host based processor that the batch should be closed. However, most Host based processors will close the batch at a predetermined time if the merchant does not perform a manual close. The merchant should check with their Merchant Services Provider to understand all options.

Important Note:

Without settling or closing the batch, the merchant will not receive any funds from credit card transactions. Check with a Nuvei integration analyst for any questions regarding batch settlement.

Section 6.2 - Service Location: link

For SOAP connections:

https://demo.spweblink.com/service/Batch.asmx?op=Batch

For standard HTTPS connections:

https:/demo.spweblink.com/service/Batch.asmx

Batch Input Parameters:

O = Optional, R = Required, C = Conditional

Parameter Name	Opt/Req/ Conditional	Max Length	Description
UserName	R	32	User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service
Password	R	32	API password associated with the user name.
WorkstationID	O	24	Value assigned by ISV to the workstation
PosID	R	24	Value assigned by Nuvei to identify the ECR/POS Station. Assigned by Nuvei to identify the ECR/POS station
Token	R	64	Value assigned by Nuvei to identify the ISV
TerminalID	R	24	Identifies individual payment terminal (lane) within a group. Assigned by Nuvei.
SerialNum	R	10	Unique Serial Number of the Payment device.
TraceNum	R	14	Unique identifier of the transaction. Assigned by Nuvei web service at the initial time of transaction.
TimeOut	R	2	Set in seconds. Maximum is 90 seconds.
TransType	R	16	BATCHCLOSE – Closes the current batch. FORCEBATCHCLOSE – Force closes the current batch, if supported by the host. BATCHCLEAR – Clears the local database. PURGEBATCH – Launches purge batch, if supported by host.
EDCType	O	10	PaymentTypes: CREDIT DEBIT CHECK EBT GIFT LOYALTY CASH
TimeStamp	R	14	Transaction Time/date stamp. The date time: YYYYMMDDhhmmss
SAFIndicator	O	1	Store and forward upload type indicator 0: New stored transactions. 1: Failed transactions 2: All (upload/resend Failed + New records) Only valid when TransType = SAFUPLOAD and DELETESAFFILE

Section 6.2.1 - Batch Response Data Definitions link

O = Optional, R = Required, C = Conditional

Parameter Name	Opt/Req/ Conditional	Max Length	Description
ResultCode	R	6	Transaction Result Code
ResultTxt	C	32	Transaction Result Text *Only returned when using JSON message format
ResultMsg	R	32	Transaction Result Text
TransType	R	20	BATCHCLOSE – Closes the current batch. FORCEBATCHCLOSE – Force closes the current batch, if supported by the host. BATCHCLEAR – Clears the local database. PURGEBATCH – Launches purge batch, if supported by host.
PosID	R	24	Value assigned by Nuvei to identify the ECR/POS Station. Assigned by Nuvei to identify the ECR/POS station.
IPaddress	R	128	IP address of initiating transaction
Port	R	9	Port of the initiating transaction
MacAddress	R	48	Identifies MAC address of payment device
TerminalID	R	24	Identifies individual payment terminal (lane) within a group. Assigned by Nuvei.
Token	R	64	Value assigned by Nuvei to identify the ISV
SerialNum	R	10	Unique Serial number of payment device.
TraceNum	R	14	Unique identifier of the transaction. Assigned by Nuvei web service at the initial time of transaction.
CreditCount	O/C	Var	Total Credit Transaction Count **Does not include Voids or Authorizations (PreAuths)
CreditAmount	O/C	Var	Total Credit Transaction Amount **Does not include Voids or Authorizations (PreAuths)
DebitCount	O/C	Var	Total Debit Transaction Count
DebitAmount	O/C	Var	Total Debit Transaction Amount
EBTCount	O/C	Var	Total EBT Transaction Count
EBTAmount	O/C	Var	Total EBT Transaction Amount
GiftCount	O/C	Var	Not supported at this time
GiftAmount	O/C	Var	Not supported at this time
LoyaltyCount	O/C	Var	Not supported at this time
LoyaltyAmount	O/C	Var	Not supported at this time
CashCount	O/C	Var	Not supported at this time
CashAmount	O/C	Var	Not supported at this time
CheckCount	O/C	Var	Not supported at this time
CheckAmount	O/C	Var	Not supported at this time
Timestamp	R	14	Transaction Time/Date Stamp: Date/Time format: YYYYMMDDhhmmss
TID	R	20	Terminal ID
MID	R	20	Merchant ID
HostTraceNum	C	32	Host Trace Number: Mandatory if the host returns a trace number. *Suggested to print this on the receipt.
BatchNum	O/C	32	Host Batch Number Mandatory if the host returns a batch number.
AuthCode	R	10	Authorization Code: Returns the transaction Auth Code from the payment processor
HostCode	R	32	Reference Number: Payment processing host reference number.
HostResponse	R	8	Host Response Code: Payment processing host response
HostMessage	O/C	32	Host Response Message: Host or Gateway Message
SAFTotalCount	O/C	4	Total number of new SAF records follow the SAF indicator.
SAFTotalAmount	O/C	8	Total amount of new SAF records follow the SAF indicator.
UploadRecords	O/C	4	Number of successful approved uploaded records.
UploadAmount	O/C	8	Amount of successful approved upload records.
FailedRecords	O/C	4	Number of failed records during the upload process.
TotalFailedDatabase	O/C	8	Number of total records in failed Database after the upload process.
DeleteRecords	O/C	4	Total number of records deleted.
ExtData	O	VAR	Varies based on data requested

Section 6.3 - Batch XML Schema link

Section 6.3.1 - SOAP 1.1 Request and Response link

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /Service/PosService.asmx HTTP/1.1
Host: demo.spweblink.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "https://secure.spweblink.com/Batch"
 
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Batch xmlns="https://secure.spweblink.com/">
      <UserName>string</UserName>
      <Password>string</Password>
      <WorkstationID>string</WorkstationID>
      <PosID>string</PosID>
      <Token>string</Token>
      <TerminalID>string</TerminalID>
      <SerialNum>string</SerialNum>
      <TraceNum>string</TraceNum>
      <TimeOut>string</TimeOut>
      <TransType>string</TransType>
      <EDCType>string</EDCType>
      <Timestamp>string</Timestamp>
      <SAFIndicator>string</SAFIndicator>
    </Batch>
  </soap:Body>
</soap:Envelope>
 
 
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <BatchResponse xmlns="https://secure.spweblink.com/">
      <BatchResult>
        <ResultCode>string</ResultCode>
        <ResultTxt>string</ResultTxt>
        <ResultMsg>string</ResultMsg>
        <IPaddress>string</IPaddress>
        <PosID>string</PosID>
        <Port>string</Port>
        <MacAddress>string</MacAddress>
        <TerminalID>string</TerminalID>
        <Token>string</Token>
        <SerialNum>string</SerialNum>
        <TraceNum>string</TraceNum>
        <CreditCount>string</CreditCount>
        <CreditAmount>string</CreditAmount>
        <DebitCount>string</DebitCount>
        <DebitAmount>string</DebitAmount>
        <EBTCount>string</EBTCount>
        <EBTAmount>string</EBTAmount>
        <GiftCount>string</GiftCount>
        <GiftAmount>string</GiftAmount>
        <LoyaltyCount>string</LoyaltyCount>
        <LoyaltyAmount>string</LoyaltyAmount>
        <CashCount>string</CashCount>
        <CashAmount>string</CashAmount>
        <CheckCount>string</CheckCount>
        <CheckAmount>string</CheckAmount>
        <Timestamp>string</Timestamp>
        <TID>string</TID>
        <MID>string</MID>
        <HostTraceNum>string</HostTraceNum>
        <BatchNum>string</BatchNum>
        <AuthCode>string</AuthCode>
        <HostCode>string</HostCode>
        <HostResponse>string</HostResponse>
        <HostMessage>string</HostMessage>
        <SAFTotalCount>string</SAFTotalCount>
        <SAFTotalAmount>string</SAFTotalAmount>
        <UploadRecords>string</UploadRecords>
        <UploadAmount>string</UploadAmount>
        <FailedRecords>string</FailedRecords>
        <TotalFailedDatabase>string</TotalFailedDatabase>
        <DeleteRecords>string</DeleteRecords>
        <ExtData>string</ExtData>
      </BatchResult>
    </BatchResponse>
  </soap:Body>
</soap:Envelope>

Section 6.3.2 - SOAP 1.2 Request and Response link

The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values.

POST /Service/PosService.asmx HTTP/1.1
Host: demo.spweblink.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <Batch xmlns="https://secure.spweblink.com/">
      <UserName>string</UserName>
      <Password>string</Password>
      <WorkstationID>string</WorkstationID>
      <PosID>string</PosID>
      <Token>string</Token>
      <TerminalID>string</TerminalID>
      <SerialNum>string</SerialNum>
      <TraceNum>string</TraceNum>
      <TimeOut>string</TimeOut>
      <TransType>string</TransType>
      <EDCType>string</EDCType>
      <Timestamp>string</Timestamp>
      <SAFIndicator>string</SAFIndicator>
    </Batch>
  </soap12:Body>
</soap12:Envelope>
 
 
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <BatchResponse xmlns="https://secure.spweblink.com/">
      <BatchResult>
        <ResultCode>string</ResultCode>
        <ResultTxt>string</ResultTxt>
        <ResultMsg>string</ResultMsg>
        <IPaddress>string</IPaddress>
        <PosID>string</PosID>
        <Port>string</Port>
        <MacAddress>string</MacAddress>
        <TerminalID>string</TerminalID>
        <Token>string</Token>
        <SerialNum>string</SerialNum>
        <TraceNum>string</TraceNum>
        <CreditCount>string</CreditCount>
        <CreditAmount>string</CreditAmount>
        <DebitCount>string</DebitCount>
        <DebitAmount>string</DebitAmount>
        <EBTCount>string</EBTCount>
        <EBTAmount>string</EBTAmount>
        <GiftCount>string</GiftCount>
        <GiftAmount>string</GiftAmount>
        <LoyaltyCount>string</LoyaltyCount>
        <LoyaltyAmount>string</LoyaltyAmount>
        <CashCount>string</CashCount>
        <CashAmount>string</CashAmount>
        <CheckCount>string</CheckCount>
        <CheckAmount>string</CheckAmount>
        <Timestamp>string</Timestamp>
        <TID>string</TID>
        <MID>string</MID>
        <HostTraceNum>string</HostTraceNum>
        <BatchNum>string</BatchNum>
        <AuthCode>string</AuthCode>
        <HostCode>string</HostCode>
        <HostResponse>string</HostResponse>
        <HostMessage>string</HostMessage>
        <SAFTotalCount>string</SAFTotalCount>
        <SAFTotalAmount>string</SAFTotalAmount>
        <UploadRecords>string</UploadRecords>
        <UploadAmount>string</UploadAmount>
        <FailedRecords>string</FailedRecords>
        <TotalFailedDatabase>string</TotalFailedDatabase>
        <DeleteRecords>string</DeleteRecords>
        <ExtData>string</ExtData>
      </BatchResult>
    </BatchResponse>
  </soap12:Body>
</soap12:Envelope>

Section 6.3.3 - HTTPS GET Request and Response link

The following is a sample HTTPS GET request and response. The placeholders shown need to be replaced with actual values.

GET /Service/PosService.asmx/Batch?UserName=string&Password=string&WorkstationID=string&PosID=string&Token=string&TerminalID=string&SerialNum=string&TraceNum=string&TimeOut=string&TransType=string&EDCType=string&Timestamp=string&SAFIndicator=string HTTP/1.1
Host: demo.spweblink.com
 
 
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<PosBatchResult xmlns="https://secure.spweblink.com/">
  <ResultCode>string</ResultCode>
  <ResultTxt>string</ResultTxt>
  <ResultMsg>string</ResultMsg>
  <IPaddress>string</IPaddress>
  <PosID>string</PosID>
  <Port>string</Port>
  <MacAddress>string</MacAddress>
  <TerminalID>string</TerminalID>
  <Token>string</Token>
  <SerialNum>string</SerialNum>
  <TraceNum>string</TraceNum>
  <CreditCount>string</CreditCount>
  <CreditAmount>string</CreditAmount>
  <DebitCount>string</DebitCount>
  <DebitAmount>string</DebitAmount>
  <EBTCount>string</EBTCount>
  <EBTAmount>string</EBTAmount>
  <GiftCount>string</GiftCount>
  <GiftAmount>string</GiftAmount>
  <LoyaltyCount>string</LoyaltyCount>
  <LoyaltyAmount>string</LoyaltyAmount>
  <CashCount>string</CashCount>
  <CashAmount>string</CashAmount>
  <CheckCount>string</CheckCount>
  <CheckAmount>string</CheckAmount>
  <Timestamp>string</Timestamp>
  <TID>string</TID>
  <MID>string</MID>
  <HostTraceNum>string</HostTraceNum>
  <BatchNum>string</BatchNum>
  <AuthCode>string</AuthCode>
  <HostCode>string</HostCode>
  <HostResponse>string</HostResponse>
  <HostMessage>string</HostMessage>
  <SAFTotalCount>string</SAFTotalCount>
  <SAFTotalAmount>string</SAFTotalAmount>
  <UploadRecords>string</UploadRecords>
  <UploadAmount>string</UploadAmount>
  <FailedRecords>string</FailedRecords>
  <TotalFailedDatabase>string</TotalFailedDatabase>
  <DeleteRecords>string</DeleteRecords>
  <ExtData>string</ExtData>
</PosBatchResult>

Section 6.3.4 - HTTPS POST Request and Response link

The following is a sample HTTPS POST request and response. The placeholders shown need to be replaced with actual values.

POST /Service/PosService.asmx/Batch HTTP/1.1
Host: demo.spweblink.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
 
UserName=string&Password=string&WorkstationID=string&PosID=string&Token=string&TerminalID=string&SerialNum=string&TraceNum=string&TimeOut=string&TransType=string&EDCType=string&Timestamp=string&SAFIndicator=string
 
 
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<PosBatchResult xmlns="https://secure.spweblink.com/">
  <ResultCode>string</ResultCode>
  <ResultTxt>string</ResultTxt>
  <ResultMsg>string</ResultMsg>
  <IPaddress>string</IPaddress>
  <PosID>string</PosID>
  <Port>string</Port>
  <MacAddress>string</MacAddress>
  <TerminalID>string</TerminalID>
  <Token>string</Token>
  <SerialNum>string</SerialNum>
  <TraceNum>string</TraceNum>
  <CreditCount>string</CreditCount>
  <CreditAmount>string</CreditAmount>
  <DebitCount>string</DebitCount>
  <DebitAmount>string</DebitAmount>
  <EBTCount>string</EBTCount>
  <EBTAmount>string</EBTAmount>
  <GiftCount>string</GiftCount>
  <GiftAmount>string</GiftAmount>
  <LoyaltyCount>string</LoyaltyCount>
  <LoyaltyAmount>string</LoyaltyAmount>
  <CashCount>string</CashCount>
  <CashAmount>string</CashAmount>
  <CheckCount>string</CheckCount>
  <CheckAmount>string</CheckAmount>
  <Timestamp>string</Timestamp>
  <TID>string</TID>
  <MID>string</MID>
  <HostTraceNum>string</HostTraceNum>
  <BatchNum>string</BatchNum>
  <AuthCode>string</AuthCode>
  <HostCode>string</HostCode>
  <HostResponse>string</HostResponse>
  <HostMessage>string</HostMessage>
  <SAFTotalCount>string</SAFTotalCount>
  <SAFTotalAmount>string</SAFTotalAmount>
  <UploadRecords>string</UploadRecords>
  <UploadAmount>string</UploadAmount>
  <FailedRecords>string</FailedRecords>
  <TotalFailedDatabase>string</TotalFailedDatabase>
  <DeleteRecords>string</DeleteRecords>
  <ExtData>string</ExtData>
</PosBatchResult>

Section 6.3.5 - JSON Format link

POST /Service/PosService.asmx/Batch HTTP/1.1
Host: demo.spweblink.com
Content-Type: application/json; charset=utf-8
Content-Length: length
 
{
	"Batch": {
		"UserName": "string",
		"Password": "string",
		"WorkstationID": "string",
		"PosID": "string",
		"Token": "string",
		"TerminalID": "string",
		"SerialNum": "string",
		"TraceNum": "string",
		"TimeOut": "string",
		"TransType": "string",
		"EDCType": "string",
		"Timestamp": "string",
		"SAFIndicator": "string",
		"_xmlns": "https://secure.spweblink.com/"
	}
}
 
{
	" PosBatchResult": {
		" PosBatchResult": {
			"ResultCode": "string",
			"ResultTxt": "string",
			"ResultMsg": "string",
			"IPaddress": "string",
			"PosID": "string",
			"Port": "string",
			"MacAddress": "string",
			"TerminalID": "string",
			"Token": "string",
			"SerialNum": "string",
			"TraceNum": "string",
			"CreditCount": "string",
			"CreditAmount": "string",
			"DebitCount": "string",
			"DebitAmount": "string",
			"EBTCount": "string",
			"EBTAmount": "string",
			"GiftCount": "string",
			"GiftAmount": "string",
			"LoyaltyCount": "string",
			"LoyaltyAmount": "string",
			"CashCount": "string",
			"CashAmount": "string",
			"CheckCount": "string",
			"CheckAmount": "string",
			"Timestamp": "string",
			"TID": "string",
			"MID": "string",
			"HostTraceNum": "string",
			"BatchNum": "string",
			"AuthCode": "string",
			"HostCode": "string",
			"HostResponse": "string",
			"HostMessage": "string",
			"SAFTotalCount": "string",
			"SAFTotalAmount": "string",
			"UploadRecords": "string",
			"UploadAmount": "string",
			"FailedRecords": "string",
			"TotalFailedDatabase": "string",
			"DeleteRecords": "string",
			"ExtData": "string"
		},
		"_xmlns": "https://secure.spweblink.com/"
	}
}

Developers

Chapter 6 – Batch Method