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