1.0 Introduction to the Direct Mode 3.1 Protocol

• Interactive Payment Forms
• Virtual Terminal
• Emulation Modes for backward compatibility with competitor's interfaces
• Interactive Batch Upload
• Direct Mode
• Direct Mode Batch

1.1 Direct Mode Overview

Transaction data is sent to our system from the back-end of the Merchant's server by software written or installed by the merchant. This gives the Merchant the ability to completely customize and integrate real time payment processing into his own application. To implement a Direct Mode client, familiarity with sockets and network programming is required.

1.2 Direct Mode Clients

1.3 Principles of Direct Mode Operation

A transaction is initiated by sending an HTTP POST to our host. The host will respond momentarily with the transaction result on the same socket. All data is URL encoded, just like a standard <form> POST from a browser.

1.4 Host addresses and ports

Host	Port	Path	Description
secure.netbilling.com	1401 (http1) 1402 (https)	/gw/sas/getid3.1	ID generator
		/gw/sas/direct3.1	Transaction interface
		/gw/sas/settle3.1	Batch settlement interface
	1403	/	VerisignTM 3 compatibility (not documented here)

Table 1.4.1
1 = Unencrypted HTTP should NOT be used except for testing.

1.5 A quick example

Parameter	Value
pay_type	C
tran_type	A
account_id	110006559149
card_number	4444333322221186
card_expire	0909
amount	5.00

Table 1.5.1

We can expect to receive the following parameters back in the response:

Parameter	Value
status_code	?
trans_id	?
auth_code	?
auth_date	?
auth_msg	?
avs_code	?
cvv2_code	?
ticket_code	?

Table 1.5.2

See the Protocol Response Reference section for more information.

First, the URL encoded HTTP POST request is assembled and sent to secure.netbilling.com port 1401:

	POST /gw/sas/direct3.1 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Type: application/x-www-form-urlencoded
	Content-Length: 104

	pay_type=C&tran_type=A&account_id=110006559149&card_number=4444333322221186&card_expire=0909&amount=5.00

	HTTP/1.0 200 OK Approved
	Connection: close
	Content-Type: application/x-www-form-urlencoded
	Content-Length: 160

	auth_msg=TEST+APPROVED&ticket_code=XXXXXXXXXXXXXXX&avs_code=X&auth_date=2004-06-09+22%3A55%3A08&status_code=T&trans_id=109704163690&auth_code=999999&cvv2_code=M

That's all it takes to execute a basic transaction. In Unix/Linux environments, netcat(1) or nc(1) can be used to recreate this example.

2.0 Protocol Request Reference

2.1 Required Request Parameters

1. Select the transaction type (tran_type) you need to program.
2. Look at the Required parameter box for that transaction type, it will enumerate the minimum required parameters.
3. Whenever a <bracketed> parameter group name is specified, go to the Parameter Group Table.
4. Locate the corresponding parameter group row(s) in the Parameter Group Table.
5. For rows with no Special condition the Required and Typical parameters will always apply.
6. For rows with special conditions, determine whether those rows apply to your transaction based on the Special condition column.
7. Each parameter is explained in more detail in the Parameter Definition Table.

For example, the minimum required parameters for a Credit Card Sale are: account_id, tran_type, pay_type, amount, card_number, card_expire, card_cvv2, bill_name1, bill_name2, bill_street, bill_zip and bill_country.

Transaction Type Table
tran_type =	Required	Optional, commonly used	Special
"A" (auth1)	account_id tran_type <payment information> <customer information>	trans_id <purchase information> <shipping information> <level 2 information>	dynip_sec_code <membership>3 <recurring billing>3
"S" (sale1)	account_id tran_type <payment information> <customer information>	trans_id <purchase information> <shipping information> <level 2 information>
"R" (refund1)	account_id tran_type orig_id	trans_id amount <purchase information>
"C" (credit1)	account_id tran_type <payment information> <customer information>	trans_id <purchase information>
"D" (capture1)	account_id tran_type orig_id	amount
"B" (batch settle2)	account_id tran_type pay_type

Transaction Type Table - Table 2.1.1
1 = Post to /gw/sas/direct3.1
2 = Post to /gw/sas/settle3.1 - notice that normally settlements are performed automatically, and this operation is not necessary.
3 = Only supported for tran_type "A" or "S"

Parameter Group Table
Parameter group	Special condition	Required parameters	Typical
<payment information>		pay_type amount	cisp_storage disable_fraud_checks disable_negative_db disable_email_receipts
	pay_type=C (credit card)	card_number card_expire card_cvv2 or card_track1 or card_track2	force_code disable_avs disable_cvv2 3ds_cavv 3ds_xid
	pay_type=K (check)	account_number cust_ip assent_key	bill_photo_id_no bill_photo_id_state bill_tax_id_no bill_birth_date
	pay_type=S (stored value)	card_number card_pin
	PCI repeat billing	account_number
<purchase information>			site_tag description misc_info user_data
	pay_type=K (check)	misc_info
<customer information>		bill_name1 bill_name2 bill_street bill_zip bill_country	bill_city bill_state cust_email cust_phone cust_ip cust_host cust_browser
<shipping information>			ship_name1 ship_name2 ship_street ship_city ship_state ship_zip ship_country courier_tracking
<level 2 information>			tax_amount ship_amount purch_order
<membership>		site_tag member_username member_duration	member_password member_memo
<recurring billing>		recurring_amount recurring_period	recurring_count recurring_prorate

Parameter Group Table - Table 2.1.2

2.2 Request Parameter Definitions

3.0 Protocol Response Reference

3.1 Transaction Response Parameter Definitions

IMPORTANT NOTE: Properly implemented client software --

• MUST NOT depend on the order of the response fields
• MUST ignore unknown fields (additional response parameters may be added without prior notice)

Transaction Response Parameter Definition Table
status_code	Single character status code. 1 - Successful monetary transaction I - Pending transaction, such as an unfunded check payment T - Successful auth only transaction 0 - Failed transaction. Consult auth_msg and reason_code2 F - Settlement failure or returned NBCheck transaction. Not applicable at authorization time D - Duplicate transaction. The trans_id of the original transaction will be returned Any unexpected status code other than "0" and "F" should be interpreted as a successful transaction.
trans_id	If trans_id was supplied in the request, the same code will be returned (except for Duplicate transaction errors.) If trans_id was not supplied in the request, a unique system generated ID will be returned.
auth_code	A 6 digit bank authorization code for the transaction.
auth_date	This is the date and time in GMT (UTC) when the transaction was authorized by the system. "YYYY-MM-DD HH:MM:SS" format.
auth_msg	A human readable approval message, for example "APPROVED 123456", or "DECLINED 05". These messages are processor specific, may change, and are not intended to be machine readable.
avs_code	Single character AVS result code. See the AVS popup window in the online administration system for a list of codes.
cvv2_code	Single character CVV2 result code. See the CVV2 popup window in the online administration system for a list of codes.
ticket_code	Typically not used. Processor specific additional transaction reference code.
reason_code2	Typically not used. Processor specific additional DECLINE-reason code. Consult the transaction details screen for a declined transaction in the online administration system for verbose reason code messages.
member_id	Returned when a new subscriber/member was added.
recurring_id	Returned when a recurring billing record was established for a new subscriber/member.
settle_amount	The settlement amount. The same as the request amount, except for Dynamic Currency Conversion merchants, where this field together with settle_currency indicate the actual amount and currency billed to the cardholder.
settle_currency	The settlement currency, typically "USD". For Dynamic Currency Conversion merchants, this field together with settle_amount indicate the actual amount and currency billed to the cardholder.

Table 3.1.1

3.2 Batch Settle Response Parameter Definitions

	"STATUS","PAY_TYPE","ID","REPORT_DATE","CLOSE_BALANCE","CLOSE_MSG"
	"1","C","200522350933","2005-03-07 23:59:19","999.99","TEST BATCH"
	"O","K","","","",""

Settlement Response Parameter Definition Table
STATUS	Single character batch settlement status code. 1 - (one) Successful batch settlement 0 - (zero) Failed to settle batch O - (big-O) No currently open transactions to settle Any unexpected status code other than "0" and "O" should be interpreted as a successful settlement.
PAY_TYPE	Single character pay_type, echoed from request.
ID	System ID number uniquely identifying the batch settlement record.
REPORT_DATE	This is the date and time in GMT (UTC) when the batch settlement was performed. "YYYY-MM-DD HH:MM:SS" format.
CLOSE_BALANCE	The settlement balance. Positive for net deposits, negative if there are more refunds than sales in the batch.
CLOSE_MSG	A human readable settlement message, for example "BATCH SETTLED". These messages are processor specific, may change, and are not intended to be machine readable.

Table 3.2.1

4.0 Exception Reporting

4.1 Exception Example

	POST /gw/sas/direct3.1 HTTP/1.0
	Host: secure.netbilling.com:1401
	Content-Type: application/x-www-form-urlencoded
	Content-Length: 104

	pay_type=C&tran_type=A&account_ix=110006559149&card_number=4444333322221186&card_expire=0909&amount=5.00

	HTTP/1.0 604 Missing Parameter (account_id)
	Connection: close
	Content-Type: text/plain
	Content-Length: 0

4.2 Exception codes and handling

Codes 699 and 799 are general codes returned for many different reasons. If you need to do special processing for one of those codes, your application also needs to look at the first 5 digits of the HTTP message in order to match a particular error.

Exception code ranges
600 - 698	Exception is most likely due to invalid input. The HTTP message contains a human-readable error message.
700 - 798	Exception is most likely due to processing error. The HTTP message contains a human-readable error message.
699, 799	The HTTP message will begin with an addition 5 digit machine-readable code that is used to further narrow down the error in software exception handling. For example: HTTP/1.0 699 20112: Invalid card expiration date 0x09 Connection: close Content-Type: text/plain Content-Length: 0 In this example, 20112 indicates that an invalid card expiration date was given.

Table 4.2.1

5.0 Special Feature Reference

5.1 ID Generation

NOTE: You should never send a "home made" trans_id number. When using this field, all trans_id numbers must be obtained using the getid3.1 method.

ID numbers are obtained by a GET or POST request to http://secure.netbilling.com:1401/gw/sas/getid3.1. For high speed applications that wish to take advantage of ID number caching, up to 10 IDs can be requested simultaneously, by passing a number (1-10) in the body of a POST, or in the query string of a GET request. e.g. http://secure.netbilling.com:1401/gw/sas/getid3.1?3.

The ID numbers are returned in the body of the text/plain response. Multiple IDs are separated by new-line characters.

5.2 PCI Compliant Storage, Repeat Billing, Up-Selling and Cross-Selling

To take advantage of this feature, the cisp_storage=1 parameter must be specified for the initial transaction. The Transaction ID (trans_id) for that transaction, together with the last 5 digits of the card number become the virtual account number handle for that customer.

To perform a future repeat billing for the same customer, instead of having to store and specify the card number and billing address again, simply send "CS:121212121212:4444" as the card_number/account_number, where 121212121212 is the trans_id of the original transaction, and 4444 is the last 4 digits of the card number (optional).

To change any of the stored information, such as the billing address, the updated information can be specified when issuing a Repeat Billing, which will over-ride the previously stored information. The new trans_id for the updated transaction can be used in the future to perform another Repeat Billing using the updated default information.

This feature can be used across accounts, which makes it possible for a merchant's affiliates to bill one of the merchant's customers, without having to know the card number or billing information. This can be used to implement cross-selling partnerships. In order for a merchant to allow its affiliates to cross-bill its customers, the partners must first be authorized by entering their account numbers on the Credit Card Setup page in the online adminstration system under PCI Managed Storage, Authorized Partners. The merchant needs to share each appropriate "CS:" virtual account number with the affiliate, in accordance with their mutual agreement.

For example, a merchant may have a checkbox on its payment form for a special offer from one of its affiliates. If a customer selects to take advantage of this offer, after completing the transaction, the merchant will send the virtual "CS:" account number to the affiliate. The affiliate will then proceed to bill the customer for the sale and ship the product.

5.3 Subscription and Recurring Billing

Membership and recurring billing records can be automatically managed by the system, including PCI compliant storage of cardholder data. While these features are primarily intended to automate much of the management for developers of member-based websites, this feature can be used by any merchants that are interested in setting up some form of automated billing for their customers.

All recurring billing records that will be setup for automatic management must be created in association with a membership. The setup of such recurring billing records can be accomplished by including the "site_tag" parameter as well as all relevant and required "Membership and Recurring Billing" fields with the transaction request (as outlined in section 2.2 of this document). If this option is used all information relating to the membership and the associated recurring billing setup will be stored and processed automatically by the system. For member based websites the system can also manage the login and password information automatically by sending information to a control CGI on your webserver. The specifics of the CGI Membership postings are covered in detail in separate documentation.

Recurring billings setup through Direct Mode can be used to automatically rebill the customer's credit card to renew the membership on a regular basis. Rebilling periods can be specified as either a number of days between recurring billing attempts (ex. 1, 7, 30) or as a special period expression. If specified as a special period expression the initial membership period can also be prorated. This allows membership signups to take place at any time during the month but automatically scale the charge amount to match the possible reduced period of time until the first scheduled recurring billing.

Please note that a membership can be associated with multiple site tags by including a comma separated list of site tags as the value for the "site_tag" field instead of just a single tag. The first site tag in this list will become the member's primary site while the others will be automatically set as additional sites that membership has been granted access to.