DIRECT MODE 2.1

INTRODUCTION

Direct Mode is a direct interface to the NETbilling payment gateway, designed to be used in situations where the standard NETbilling Payment Form is not appropriate. It supports all the same functions, including check payment, Credit Card payment, membership signups, and automatic rebillings.

Using Direct Mode requires some knowledge of advanced CGI scripting or other programming techniques. Any examples given in this document will be provided in Perl. Additionally, a Perl script for Direct Mode access is available from NETbilling, and may speed your development. A Java and C Direct Mode client is also available, contact NETbilling support at 888.357.8166 for more information. Of course, developers are welcome to write their own client libraries based on this specification.

OVERVIEW

The basic transaction in Direct Mode works as follows: The merchant's system makes a standard HTTP connection to the NETbilling server, passing the transaction data in an HTTP POST operation (with the parameters encoded in the body of the request). The NETbilling system then processes the transaction, and returns either a HTTP 200 (OK) along with the relevant return values, *or* the NETbilling server will return an HTTP 400 (ERROR) and the body of the response will be set to a string indicating the reason for the error.

The URL for Direct Mode 2.1 is: https://secure.netbilling.com/gw/native/direct2.1

See the appendices for specific fields to pass. Please contact NETbilling for any additional information. E-mail support@netbilling.com.

ADVANCED FEATURES

Advanced Procedure

The most robust and secure way to issue a transaction via NETbilling's Direct Mode is to first obtain a Transaction ID from the NETbilling servers to assign to the transaction. Then if the transaction fails to return for any reason, it is still possible to track the transaction's status through the online reporting system.

To obtain a valid TransID (passing a made-up or invalid TransID can cause serious processing errors) you can query the following URL:

https://secure.netbilling.com/gw/native/getid1.0

The ID to use for the next transaction will be returned in the body of the response. It is possible to request multiple IDs simultaneously; simply append a ?x to the query URL, where x is the number of IDs to request. All the IDs will be returned int he body of the response, separated by newlines.

Each ID is valid for ONE transaction only. The script must get a new ID for each new transaction.

If the transaction should fail to return a proper response code for any reason, the status of the transaction can be gotten by querying the following url:

https://secure.netbilling.com/gw/native/poll1.0

Pass the Trans ID of the transaction to poll for in as a trans_id cgi parameter. The script will return the following values, cgi-encoded (or an error 400 if there is an error):

found = Y if found, N if not found. If found=N, it will be the only parameter returned.

status = Status code, same as RET_STATUS below (appendix B)

trans_id= The transaction ID you posted to the script

amount = Amount of the transaction

message = Human-readable status message

issue_date = Date the transaction was issued

cap_date = Date the transaction was captured

origin = Origin of transaction (V-Terminal, Direct Mode, etc)

Membership Signups

It is possible to allow NETbilling to handle membership signups for member-based websites. If this option is used, NETbilling will store the user names and passwords along with the associated transaction data. The valid login names and passwords will be sent to a control CGI on the member-based website. A sample Perl CGI for accepting this data is available from NETbilling.

The specifics of the CGI Membership postings are outside the scope of this document. Separate documentation for this feature is available from NETbilling.

Automatic Rebillings

In the case of membership signups, it is possible to automatically rebill the customer's credit card or NBCheck account to renew the membership on a regular basis. Rebilling periods can be specified as either a number of days between rebillings (1, 7, 30, etc) or as an SQL-style date expression. If specified in an SQL-style expression, the initial membership period can also be prorated. For instance, if a website renews memberships on the first of each month, and a person signs up on the 15th, they will be billed for only half a normal membership.

Note that there are legalities involved with automatic rebilling. Following the laws is the responsibility of the merchant, not NETbilling.

Modifying Existing Memberships and Rebillings

It's possible to remotely affect changes to rebilling information such as amount and period, as well as membership information such as expiration, login, and password. The full interface for this works similarly to Direct Mode and is documented in the membership update script documentation.

Crypto-Hash

Crypto-Hash is NETbilling's proprietary system for ensuring data integrity across insecure connections. While the connection to Direct Mode is typically made with a secure HTTP (https://) connection, additional security is always recommended, particularly for financial transactions.

When using Crypto-Hash, all the fields required for the transaction are passed just as normal to the Direct Mode interface. However, an MD5 checksum of the critical transaction data is also sent. If the data is compromised in transmission, NETbilling's server will reject the transaction.

The MD5 checksum is determined in the following way: In the GEN_HASHFIELDS parameter, pass a SPACE-SEPERATED list of the field names to be included in the checksum. It is highly recommended you include at least the GEN_AMOUNT and ACH_* or CARD_* fields. For instance, the GEN_HASHFIELDS parameter may contain, 'GEN_AMOUNT CARD_NUMBER CARD_EXPIRE CARD_CVV2'.

The values of the fields you have chosen should be concatenated into a single string, with the Crypto-Hash Key (set on the NETbilling server in your account config) prepended to it. To continue the example, if you NETbilling Crypto-Hash key is 'lwdf37r4j8RrzdHm4gi5' then the string would be something like,

"lwdf37r4j8RrzdHm4gi525.00412312341234123402023456" | | | | | \Crypto-hash key \ \CC # \ \CVV2 \amount \exp

Take this string and hash it using MD5, then pass it to Direct Mode in the GEN_HASHVALUE_MD5 parameter. The parameters will be encoded on NETbilling's end by the Direct Mode interface and compared to the value passed from your server. If they do not match, the transaction is rejected.

Of course, this is only secure so long as your Crypto-Hash key is secure. If you believe your crypto-hash key has been compromised, immediately generate anew one and update your scripts to reflect the new value.

Note that when using Crypto-Hash, at least TWO fields must be included, or the system will give you an error. Using less than two fields is not as secure, and not recommended.

Appendix A: Input fields

GEN_ACCOUNT

This is the number of your NETbilling merchant or agent account, as a 12-character string. Required for ALL transactions.

GEN_SITETAG

The site tag of your website configured in the NETbilling system. Required for membership transactions, optional for others.

GEN_DESCRIPTION

An optional description of the product or services paid for. Up to 4000 characters

GEN_AMOUNT

The amount of the transaction. Optional for refunds/voids as it will be taken from the amount of the original transaction. Must be 0.00 for AVS-only.

GEN_MISC_INFO

Additional miscellaneous info to accompany the transaction, up to 4000 characters.

GEN_TRANS_TYPE

Indicates the type of the transaction:

'AVS' - Address verification only, no charges

'AUTH' - Pre-Auth a charge card for later capture

'CAPTURE'- Capture a Pre-Authed charge

'SALE' - Standard charge/check transaction

'CREDIT' - Credit the charge/check account instead of charging it

'REFUND' - Will attempt a VOID or a Refund of a previous 'SALE'

'NONE' - For doing a transaction that is only a member signup, no payment

'ABORT' - Will abort a pending capture

GEN_PAYMENT_TYPE

Single-character field. 'C' for Charge, 'K' for Checks

GEN_HASHVALUE_MD5

Used for additional security in a transaction. Optional but HIGHLY recommended. See the section above on Crypto-Hash for more details.

GEN_TRANS_ID

Optionally specify the NETbilling Transaction ID for this transaction. Optional and rarely used; if the Transaction ID specified already exists, errors will occur.

GEN_MASTER_ID

An NETbilling Transaction ID returned from a previous transaction. Used for 'REFUND' type transactions, the amount of the refund/Void and other relevant data will be taken from the original transaction data.

OVERRIDE_FRAUD_CHECKS

Set to 1 to temporarly disable Fraud Defense for this particular transaction only.

CUST_IP

CUST_HOST

The customer's IP address and host. This is used for fraud screening, but is optional.

CUST_NAME1

CUST_NAME2

CUST_ADDR_STREET

CUST_ADDR_CITY

CUST_ADDR_STATE

CUST_ADDR_ZIP

CUST_ADDR_COUNTRY

CUST_PHONE

CUST_EMAIL

These fields contain all the customer's billing data. They are optional, but needed to perform Address Verification, and often including them results in alower rate for the transaction.

CARD_NUMBER

Credit Card Account Number -- required for Credit Card transactions.

CARD_EXPIRE

Credit Card expiration date, in MMYY format

CARD_CVV2

Credit Card CVV2 value. This is the three or four digit code on the back of the customer's credit card. Optional, but often will get a lower rateon the transaction

CARD_FORCE_CODE

Force code provided by credit card processor. Optional.

ACH_ROUTING

Checking account routing code. Required for check transactions.

ACH_ACCOUNT

Checking account number. Required for check transactions.

ACH_CHECKNUMBER

An optional check sequence number, provided by the customer.

ACH_ID_SSN

ACH_ID_DL

ACH_ID_TAXID

The above three fields are optional, but necessary for proper fraud screening. In any case, only ONE of the above fields will be used if provided, in this order of preference: SSN, then DL, then TAXID.

ACH_ID_STATE

The two-character postal code for the state the ID was issued in. Leave blank if inappropriate, for instance, when using SSN.

DO_MEMBER

Set to 1 for membership transactions, 0 or null for non-membership.

MEM_DURATION

Required for membership signups. Specifies how long the membership is valid for.

MEM_LOGIN

The member's login name. The transaction will return an error if this name is already in use

MEM_PASS

The member's password.

MEM_MEMO

An optional memo text field to associate with the member, and display on the edit member screen within the system

DO_REBILL

Set to 1 to start rebillings on this transaction, 0 or null for not.

REB_COUNT

The number of rebillings to perform, required for rebillings.

REB_PERIOD

The length of time between rebillings, specified in days, or an SQL date expression.

REB_AMOUNT

The amount to charge the customer's card/check account for each rebilling.

REB_PRORATE

Optional, if you use a SQL date expression for rebillings, the amount of the initial period can be prorated if a '1' is passed in this field.

Appendix B: Output fields

RET_STATUS

The definitive status of the transaction. Single-character field:

1 = Successful

0 = Failed

F = Failed

R = Returned/Voided (will not occur in this context)

T = Successful Auth-Only

I = Incomplete, but successful. This is returned from check transactions that are successful, but may still fail at a later date due to NSF. Should be responded to exactly the same as a '1'.

Any other returned codes should be interpreted as success for future compatibility.

RET_AUTH_MSG

Human-readable message describing the state of the transaction, or the reason for failure

RET_TRANS_ID

NETbilling's Transaction ID for this transaction

RET_AUTH_CODE

VISA/MC Transaction ID

RET_AVS_CODE

Address Verification response -- only for charge transactions

RET_AVS_MSG

Human readable AVS response -- only for charge transactions

RET_CARD_ISSUER

The issuer of the Credit Card, for charge transactions only.

RET_CVV2_CODE

CVV2 Verification code

RET_CVV2_MSG

Human readable CVV2 response

Appendix B: Special Notes

Multi-Threading

The Direct Mode does support multi-threading. Multiple transactions can be sent to the Direct Mode simultaneously, and each will be resolved independently.

If you take advantage of Direct Mode multi-threading, you must take into account the speed at which your processor can process transactions. You must insure that you do not send transactions faster than they can be processed by your processor (FDR, VITAL, NOVA, etc.).

FDR-OMAHA

FDR-OMAHA only allows one transaction per merchant account at a time.

Even though the NETbilling Direct Mode supports multi-threading, FDR-OMAMA does not.

Therefore, when preparing a Direct Mode script for FDR-OMAHA, scripters should single thread, waiting for a response before sending the next transaction.

Sending transactions multi-threaded on FDR-OMAHA can result in slower than usual transaction responses and transaction loss at batch close time. Since the batches on OMAHA cannot exceed 500 transactions, this could mean a loss of a handful of transactions in every 500 sent.