Chapter 6 – Batch Method

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:

 

  1. 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.

 

  1. 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:

 

  1. 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.

  2. 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/" } }

Need Help?

How can we help you today?  Our team is standing by and just a click away.