Direct Mode 3.0 Batch Protocol Documentation

Direct Mode 3.0 Batch Protocol Documentation


1.0 Introduction to the Direct Mode 3.0 Batch Protocol

Netbilling, a leader in high-performance digital payment processing solutions, provides multiple interfaces to its transaction processing system. These interfaces include This documentation describes version 3.0 of the Direct Mode Batch interface.

1.1 Direct Mode Batch Overview

Direct Mode Batch allows advanced merchants to automate uploading, processing and downloading of large batch files of transactions. Using this interface, 50,000 or more transactions per hour can be processed within a single account.

It's similar to the manual Batch Upload tool available within the online administration system, but instead of requiring a user to upload and download the batch files using a browser, Direct Mode Batch allows merchant-side software to control the batch processing.

1.2 Direct Mode Batch Clients

If you are using Java, you can take advantage of our Java Client for Direct Mode 3.0 Batch, which handles all the protocol encapsulation, encoding and decoding for you. A stand-alone Java agent (BatchAgent) is also part of the package, which allows batch input files to simply be saved into a "drop directory" for automatic processing by the BatchAgent. Upon completion the result files are automatically written to the same directory, with a .out extension.

1.3 Principles of Direct Mode Batch Operation

To make client implementation as simple as possible, the Direct Mode 3.0 Batch protocol is based on the standard HTTP protocol and SSL (HTTPS) encryption. Most modern languages have built in libraries that can be used to implement HTTP clients with very little effort.

A transaction is initiated by sending an HTTP POST to our host. The host will respond momentarily with the request result on the same socket. All data files are CSV encoded, e.g. data fields are double-quote enclosed and comma separated. Each record (line) is separated by new-line "\n" or carriage-return and new-line "\r\n". If a field needs to contain a double-quote character, it should be doubled. For example, Joe "Jr" Jones would be encoded as "Joe ""Jr"" Jones". Most spreadsheet software can export to CSV format.

Commands and Status messages are URL encoded.

Batch mode is asynchronous, meaning that clients have to poll the system periodically to find out when their batch has finished processing; it is not possible to wait on a single socket for the batch to finish.

1.4 Batch file format

All batch files are multi-line Comma Separated Values (CSV) files. The first line of each file defines the order and content of the fields. See the example below for more information.

1.5 Host addresses and ports

The following host addresses and ports are used for Direct Mode 3.0 Batch:

HostPortPathDescription
secure.netbilling.com1401/gw/sas/getid3.0Unencrypted (HTTP) ID generator
secure.netbilling.com1401 /gw/sas/directbatch3.0/validate
/gw/sas/directbatch3.0/upload
/gw/sas/directbatch3.0/start
/gw/sas/directbatch3.0/stop
/gw/sas/directbatch3.0/status
/gw/sas/directbatch3.0/download
Unencrypted (HTTP) batch interface (not for production)
secure.netbilling.com1402 /gw/sas/directbatch3.0/validate
/gw/sas/directbatch3.0/upload
/gw/sas/directbatch3.0/start
/gw/sas/directbatch3.0/stop
/gw/sas/directbatch3.0/status
/gw/sas/directbatch3.0/download
Encrypted (HTTPS) batch interface
Table 1.5.1

2.0 A batch example

In this example, we wish to send the following batch to the host for processing:

TRAN_TYPEPAY_TYPECARD_NUMBERCARD_EXPIREAMOUNT
SC444433332222301809095.01
SC444433332222302610095.02
SC444433332222303411095.03
Table 2.0.1

We can expect to receive the following batch response file back:

TRAN_TYPEPAY_TYPECARD_NUMBERCARD_EXPIREAMOUNTTRANS_IDSTATUSAVS_RESULTCVV_RESULTAUTH_CODEAUTH_MSGLOCAL_AUTH_DATE
SC444433332222301809095.01???????
SC444433332222302610095.02???????
SC444433332222303411095.03???????
Table 2.0.2

2.1 Batch Data Validation

The validate command is used to ensure that the batch file doesn't have any formatting errors or missing fields. It's an optional step, but a good idea unless you're sure the batch file is error free. 
	POST /gw/sas/directbatch3.0/validate?account_id=110006559149 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Type: text/comma-separated-values
	Content-Length: 183

	"TRAN_TYPE","PAY_TYPE","CARD_NUMBER","CARD_EXPIRE","AMOUNT"
	"S","C","4444333322223018","0909","5.01"
	"S","C","4444333322223026","1009","5.02"
	"S","C","4444333322223034","1109","5*03"
Notice that there is a deliberate error in the amount field for the last record. This is used in the example to demonstrate the error handling. The server will respond with: 
	HTTP/1.0 200 OK
	Rejected-Records: 1
	Accepted-Records: 2
	Connection: close
	Content-Type: text/comma-separated-values
	Content-Length: 52

	"LINE","ERROR","DATA"
	"3","Invalid AMOUNT","5*03"
During validation data is immediately screened for formatting errors and missing fields. If any errors are detected, they will all be returned, 1 per line, in CSV format in the response body. The number of good (accepted) and bad (rejected) records are returned as HTTP header fields.

2.2 Batch Data Upload

An upload request is identical to a validate request, except for the URL having the upload command rather than a validate command in it. The upload command causes the batch data to be stored in a staging table, ready for processing. 
	POST /gw/sas/directbatch3.0/upload?account_id=110006559149 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Type: text/comma-separated-values
	Content-Length: 183

	"TRAN_TYPE","PAY_TYPE","CARD_NUMBER","CARD_EXPIRE","AMOUNT"
	"S","C","4444333322223018","0909","5.01"
	"S","C","4444333322223026","1009","5.02"
	"S","C","4444333322223034","1109","5.03"
The response is also similar to the validate response. It contains one additional header field, Batch-Id, which is a reference to the batch which we will need later. 
	HTTP/1.0 200 OK
	Rejected-Records: 0
	Accepted-Records: 3
	Batch-Id: 109706081619
	Connection: close
	Content-Type: text/comma-separated-values
	Content-Length: 0
This is how batch data is loaded into the system. No transaction processing will occur yet, however, the uploaded data is immediately screened for formatting errors, just like during validation. If any errors are detected, it will not abort the batch upload, but the invalid records will not be loaded. Instead, information on the errors are returned, 1 per line, in CSV format in the upload response body. The number of good (loaded) and bad (rejected) records is returned as header fields.

2.3 Starting Batch Processing

Referencing the Batch ID returned during the upload, we now instruct the system to start processing the batch using the following request: 
	POST /gw/sas/directbatch3.0/start?account_id=110006559149&batch_id=109706081619 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Length: 0
The system will respond with the URL encoded current batch status (STARTING), the number of total_records (3), records_done so far (0), approvals (0), declines (0) and exceptions (0). 
	HTTP/1.0 200 OK
	Batch-Id: 109706081619
	Connection: close
	Content-Type: application/x-www-form-urlencoded
	Content-Length: 82

	approvals=0&total_records=3&status=STARTING&records_done=0&exceptions=0&declines=0

2.4 Checking the status of a batch

To determine whether processing has completed, we use the status command: 
	POST /gw/sas/directbatch3.0/status?account_id=110006559149&batch_id=109706081619 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Length: 0
The response format is the same as for the start command. 
	HTTP/1.0 200 OK
	Batch-Id: 109706081619
	Connection: close
	Content-Type: application/x-www-form-urlencoded
	Content-Length: 82

	approvals=3&total_records=3&status=FINISHED&records_done=3&exceptions=0&declines=0
In the example above, the status field indicates that the batch has FINISHED processing, and is ready for download.

2.5 Downloading the batch processing result

The download command will return the finished batch processing results. 
	POST /gw/sas/directbatch3.0/download?account_id=110006559149&batch_id=109706081619 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Length: 0
All the uploaded fields, even those (if any) not recognized by our system such as custom user fields, will be returned back in the same order. The response fields will be appended at the end of each line. 
	HTTP/1.0 200 OK
	Batch-Id: 109706081619
	Connection: close
	Content-Type: text/comma-separated-values
	Content-Length: 497

	"TRAN_TYPE","PAY_TYPE","CARD_NUMBER","CARD_EXPIRE","AMOUNT","TRANS_ID","STATUS","AVS_RESULT","CVV2_RESULT","AUTH_CODE","AUTH_MSG","LOCAL_AUTH_DATE"
	"S","C","4444333322223018","0909","5.01","109721726994","1","X","M","999999","TEST APPROVED","2004-06-16 17:05:29"
	"S","C","4444333322223026","1009","5.02","109721792530","1","X","M","999999","TEST APPROVED","2004-06-16 17:05:29"
	"S","C","4444333322223034","1109","5.03","109789687891","1","X","M","999999","TEST APPROVED","2004-06-16 17:05:29"

3.0 Protocol Request Reference

In this section, all input field names recognized by the system are listed. Other fields names (columns) can be included. They will simply be passed through into the response file without consideration by the system.

3.1 Request Fields

The request fields are the same as in standard (non-batch) Direct Mode 3.0. Please refer to that specification for details. The rules for when parameters are required are also the same; please refer to this section of the Direct Mode 3.0 specification. The only exception is for PAY_TYPE, which defaults to "C" (credit cards) for each batch record if not specified, and is therefore not required.

Input Fields
Column headingCorresponding parameter name and definition
"PAY_TYPE" pay_type
"TRAN_TYPE" tran_type
"SITE_TAG" site_tag
"AMOUNT" amount
"CARD_NUMBER" card_number
"CARD_EXPIRE" card_expire
"CARD_CVV2" card_cvv2
"NAME1" bill_name1
"NAME2" bill_name2
"BILL_STREET" bill_street
"BILL_CITY" bill_city
"BILL_STATE" bill_state
"BILL_ZIP" bill_zip
"BILL_COUNTRY" bill_country
"PHONE" cust_phone
"EMAIL" cust_email
"DESCRIPTION" description
"FORCE_CODE" force_code
"ORIG_ID" orig_id
Input Fields Table - Table 3.1.1

4.0 Protocol Response Reference

In this section, all response parameters returned by the system are listed. These fields are appended to the end of each input record to form the corresponding output record.

4.1 Response Fields

The response fields are a subset of the standard (non-batch) Direct Mode 3.0 protocol. Please refer to the standard protocol response reference for more details. The only exception is for LOCAL_AUTH_DATE, which is only returned for batch processing. In standard Direct Mode, the GMT time is returned instead.

Output Fields
Column headingCorresponding parameter name and definition
"TRANS_ID" System generated Transaction ID for each transaction
"STATUS" status_code
"AVS_RESULT" avs_code
"CVV2_RESULT" cvv2_code
"AUTH_CODE" auth_code
"AUTH_MSG" auth_msg
"LOCAL_AUTH_DATE" Local transaction time in YYYY-MM-DD HH:MM:SS format
Output Fields Table - Table 4.1.1

5.0 Exception Reporting

In Direct Mode Batch, exceptions normally only occur due to programming errors, such as trying to download a batch that is not finished yet, etc. Please refer to the section on Exception Reporting in the Direct Mode 3.0 specification for general exception handling guidelines.