Direct Mode 3.2 Batch Protocol Documentation
1.0 Introduction to the Direct Mode 3.2 Batch Protocol
Ezic, a leader in high-performance digital payment processing solutions,
provides multiple interfaces to its transaction processing system. These interfaces include
- Interactive Payment Forms
- Virtual Terminal
- Emulation Modes for backward compatibility with competitor's interfaces
- Interactive Batch Upload
- Direct Mode
- Direct Mode Batch
This documentation describes version 3.2 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.2 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.2 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.2 Batch:
| Host | Port | Path | Description |
| secure.ezic.com | 1401 | /gw/sas/getid3.2 | Unencrypted (HTTP) ID generator |
| secure.ezic.com | 1401 |
/gw/sas/directbatch3.2/validate
/gw/sas/directbatch3.2/upload
/gw/sas/directbatch3.2/start
/gw/sas/directbatch3.2/stop
/gw/sas/directbatch3.2/status
/gw/sas/directbatch3.2/download
| Unencrypted (HTTP) batch interface
(not for production) |
| secure.ezic.com | 1402 |
/gw/sas/directbatch3.2/validate
/gw/sas/directbatch3.2/upload
/gw/sas/directbatch3.2/start
/gw/sas/directbatch3.2/stop
/gw/sas/directbatch3.2/status
/gw/sas/directbatch3.2/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_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 |
Table 2.0.1
We can expect to receive the following batch response file back:
| TRAN_TYPE | PAY_TYPE | CARD_NUMBER | CARD_EXPIRE | AMOUNT | TRANS_ID | STATUS |
| S | C | 4444333322223018 | 0909 | 5.01 | ? | ? |
| S | C | 4444333322223026 | 1009 | 5.02 | ? | ? |
| S | C | 4444333322223034 | 1109 | 5.03 | ? | ? |
| AVS_RESULT | CVV_RESULT | AUTH_CODE | AUTH_MSG | LOCAL_AUTH_DATE |
| ? | ? | ? | ? | ? |
| ? | ? | ? | ? | ? |
| ? | ? | ? | ? | ? |
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.2/validate?account_id=110006559149 HTTP/1.0
Host: secure.ezic.com:1401
User-Agent: MyDM3Client/Version:2010.Aug.20
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.2/upload?account_id=110006559149 HTTP/1.0
Host: secure.ezic.com:1401
User-Agent: MyDM3Client/Version:2010.Aug.20
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.2/start?account_id=110006559149&batch_id=109706081619 HTTP/1.0
Host: secure.ezic.com:1401
User-Agent: MyDM3Client/Version:2010.Aug.20
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.2/status?account_id=110006559149&batch_id=109706081619 HTTP/1.0
Host: secure.ezic.com:1401
User-Agent: MyDM3Client/Version:2010.Aug.20
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.2/download?account_id=110006559149&batch_id=109706081619 HTTP/1.0
Host: secure.ezic.com:1401
User-Agent: MyDM3Client/Version:2010.Aug.20
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 below behave the same as in standard (non-batch) Direct Mode 3.2.
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.2
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 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.2 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 heading | Corresponding 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.2 specification for general exception handling guidelines.