Direct Mode 3.2 Protocol Documentation

1.0 Introduction to the Direct Mode 3.2 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

1.5 A quick example

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

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:

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.

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)

3.2 Batch Settle Response Parameter Definitions

4.0 Exception Reporting

4.1 Exception Example

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.

5.0 Special Feature Reference

5.1 ID Generation

NOTE: You should never send a "home made" trans_id or member_id. When using those fields, all id numbers must be obtained using the getid3.2 method.

ID numbers are obtained by a GET or POST request to http://secure.netbilling.com:1401/gw/sas/getid3.2. 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.2?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

The system supports PCI compliant cardholder data storage, which can be used to perform Repeat Billing, up-selling and cross-selling at a later time for a previous customer, without requiring the storage of cardholder data at the merchant site.

The PCI security standards are technical and operational requirements that were created to help organizations that process card payments prevent credit card fraud, hacking and various other security vulnerabilities and threats. The standards apply to all organizations that store, process or transmit cardholder data. A company processing, storing, or transmitting cardholder data must be PCI DSS compliant.

To take advantage of this feature, PCI storage must be enabled in Step 6 of the Credit Card setup page.

To change any of the stored information, such as the billing address, the updated information can be specified when issuing a Repeat Billing, up-sell or cross-sell, and it will override the previously stored information. The new trans_id for the updated transaction can be used in the future to perform another Repeat Billing, up-sell or cross-sell using the updated default information.

Repeat Billing and Up-selling

This feature enables you to perform a future repeat-billing or up-sell for the same consumer within the same gateway account, rather than storing and specifying the card number and billing address again. Simply check "Enable PCI Compliant Repeat Billing, Up-selling and Cross-selling" in Step 6 of the Credit Cards setup page. When the feature is enabled, you would send "CS:123456789012" as the card_number, where 123456789012 is the trans_id of the original transaction.

Note: If the new transaction is to be processed through a different gateway account than the original sale, it's considered cross-selling. See below.

To allow cross-selling without an affiliate having to know the card number or billing information, simply specify a space-separated list of affiliate accounts authorized to use this feature under Authorized affiliate accounts in Step 6 of the Credit Card setup page. The affiliate must send "CS:123456789012:4444" as the card_number, where 123456789012 is the trans_id of the original transaction, and 4444 is the last 4 digits of the card number. The ":4444" is required to confirm the card number. The merchant must share each appropriate "CS:" original transaction ID and the last four digits of the card 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 "CS:" transaction id to the affiliate. The affiliate will then proceed to bill the customer for the sale and ship the product.

Note: MasterCard no longer permits cross-selling. Any affiliate that you choose to prevent from running MasterCard transactions should be listed under Authorized affiliate accounts.

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 web-server. The specifics of the CGI Membership postings are covered in detail in separate documentation.

Recurring billing setup through Direct Mode can be used to automatically re-bill the customer's credit card to renew the membership on a regular basis. Recurring billing 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 sign-ups 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.

5.4 3DSecure Version 2

If you are using a 3rd party MPI (Merchant Plugin) to authenticate transactions with 3DSecure 2, include the values returned by the MPI to the transaction in the parameters 3ds_eci, 3ds_cavv, and 3ds_xid. For example:

If you do not have an MPI but instead wish the gateway to perform the 3DSecure 2 authentication, send the enable_3ds_mpi, 3ds_mid, 3ds_currency, and 3ds_return_url parameters. For example:

At this point, the customer may or may not be required to answer a 3DSecure Challenge. There are many reasons why a 3DS Challenge may not be required. The card may not be enrolled in 3DS; The card may be enrolled but the transaction qualifies for frictionless 3DS authentication; or, some kind of error occurs. If a 3DS Challenge is not required, then the transaction processes normally, a typical Direct Mode response is returned, and there are no further steps to take. The transaction is complete.

If a 3DS Challenge is determined to be necessary, then the transaction is not sent to the processor but rather stored locally as if you had sent a tran_type=Q transaction. The Direct Mode response will contain the trans_id of the stored transaction as well as the 3ds_url and 3ds_creq parameters. For example:

You must redirect the customer to the URL you received in 3ds_url so they can type in their security information. This is the URL of the 3rd party ACS (Access Control Server). The ACS contains the authentication rules and is controlled by the Card Issuer. Thus, the URL can change from card to card. The redirect must be a POST. Set the Content_Type header of the POST to application/x-www-form-urlencoded. The payload of the POST must contain a creq parameter. Set the creq parameter to the string you received in 3ds_creq.

In addition to creq, you will most likely want to include a threeDSSessionData parameter. If included, this parameter must be Base64URL encoded without padding. This parameter can help tie challenge completion messages (CRes messages) back to their originating transactions so they can be submitted back to Direct Mode for payment processing. For example, you might encode the trans_id you received, 210742956290, as MjEwNzQyOTU2Mjkw.

To continue the previous example, you might request the customer's browser to sumbit the following POST:

The customer's browser will now be displaying a challenge webpage hosted by the ACS. The customer will be asked to type in security information. For example, they may be asked to type in a code that was texted to their phone. When the challenge is successfully completed, the ACS will send an HTTP POST to the URL you provided in 3ds_return_url. For example, you might receive the following POST from the ACS:

You would now forward this cres parameter in a new request to Direct Mode to complete the payment transaction, using 3ds_cres. Since the transaction is already stored in the gateway, it isn't necessary to submit all of the information again. Continuing with the example, threeDSSessionData=MjEwNzQyOTU2Mjkw decodes into 210742956290. That will be used to reference the transaction stored on the gateway, using the orig_id parameter. Set tran_type D to indicate you're authing and capturing an existing transaction. If the processor requires CVV2, you'll need to send that in the card_cvv2 parameter since it cannot be stored. One method of preserving the cvv2 would be to encode it into the threeDSSessionData parameter. Here is what you might post to the gateway:

When Direct Mode receives this request, it will obtain the cavv/xid from the 3DSecure network using the cres provided, then forward the transaction to the processor with cavv/xid included. Payment processing will complete as normal and a typical Direct Mode response will be returned.