NETbilling Transaction Update Protocol

NETbilling has the most powerful Direct Mode payment interfaces available in the gateway industry. These interfaces allow merchants to automate payment processing.

A new Transaction Update Mode for marking chargebacks and retrieval requests been created to compliment the NETbilling Direct Mode for payments and to allow for the automated organization, management, and updating of chargebacks. While it bears much similarity with Direct Mode for payments, Transaction Update Mode is a separate interface. Its API is similar to Transaction Update Mode.

The Transaction Update Mode does not require merchants to use Direct Mode to take advantage of its features.

This interface allows website developers to build their own interfaces to edit and manage transaction chargeback records remotely, as well as allow them to create a set of tools for use by customers on local websites.

The NETbilling online system is still available for the manual editing and updating of transaction chargeback information. The new NETbilling Transaction Update Mode is specifically added for the automating of chargeback management. The NETbilling Transaction Update Mode can be used in conjunction with other automated chargeback imports, the 'mark chargeback' tool on the View Transaction Details page, and the Data Retrieval Interface chargeback reporting tools.

This documentation is intended for a technical audience. Knowledge of HTTP standards is assumed.

URL: https://secure.netbilling.com/gw/native/tupdate1.0

You can now update transactions with a simple direct interface, similar to the interface used for processing memberships with NETbilling Member Update Mode.

This protocol is based on a standard HTTP POST. However, it should not be performed from the user's browser like a standard POST.

You should open a socket connection to the above url from a script on your server and send a standardly-formatted HTTP POST to it. The parameters discussed below go into the body of the POST in standard CGI-encoded format. You will receive a response on the same socket, as per HTTP standards.

The response will contain the code 200 for success and 400 for error. If an error has occurred, the body of the response contains a plain text description of the error and no changes will be made to the member in question. If the response code is 200, the body of the response contains a plain text success message, except when using "GET" (see C_COMMAND below). In this case, a standard CGI-encoded parameter string containing the response parameters is returned in the body.

Request Fields:

These are the fields you must send to the NETbilling Transaction Update Mode in order to process a Transaction Updates. The following set of fields are used to control the request to tupdate1.0.

C_ACCOUNT

Contains your NETbilling account number and the site tag, separated with a colon. The site tag is REQUIRED. It does NOT need to correspond to the transaction you are updating. Its sole purpose is to serve in conjunction with the control keyword (described below) to verify that the request comes from a reliable source. Example: 123412341234:TESTSITE

C_CONTROL_KEYWORD

The access control keyword definable in the NETbilling admin system (on the site config page), corresponding to the site tag you selected. This is used to verify that the request comes from a reliable source. Example: "mykeyword"

C_COMMAND

Tells the script what action to perform, as follows:

MARK_TRANS

Use this command to indicate that you wish to mark the transaction as chargedback or retrieval requested.

Additional Fields

T_TRANS_ID

The transaction id. Example: 123412341234

T_CODE

A or R or E. Send R to indicate there was a retrieval request, send A to indicate a chargeback, send E to indicate the transaction was externally refunded.

T_DISABLE_MEMBER

(Optional) Send a 1 to disable membership and stop any recurring billing

T_ADD_CARD_TO_NDB

(Optional) Send a 1 to add the card to the negative database

T_DISP_DATE

(Optional) The date the dispute was posted. The date format is YYYY-MM-DD. Leave blank to use today's date. Example: 2019-01-31

T_NOTES

(Optional) Notes to go along with the marked dispute. These are the notes that will show up in the transaction's Dispute History on the Transaction Details page. Maximum length 4000 characters.

Example Responses

The following are example responses after performing a MARK_TRANS command:

MARKED transaction 123412341234 as chargeback

MARKED transaction 123412341234 as retrieval

Transaction already marked as chargeback

Transaction already marked as retrieval

Note that other responses are possible. Treat any occurrance of the string "MARKED" as success.

Note that MARK_TRANS actions cannot be undone, as is the exsting behavior of the Transaction details 'mark chargeback' tool. Please test this tool on TEST transactions first.

Note that, like the Transaction Details page, a maximum of one retrieval request and one chargeback may be manually marked on a given transaction.