NETbilling Member 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 Membership Update Mode for Membership and Rebilling has been created to compliment the NETbilling Direct Mode for payments and to allow for the automated organization, management, and updating of Memberships and Rebillings. While it bears much similarity with Direct Mode for payments, Membership Update Mode is a separate interface

The Membership 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 memberships and rebilling records remotely, as well as allow them to create a set of tools for use by customers on local websites. The easiest way to take advantage of the automation the NETbilling Membership Update Mode allows is to place an automation script on a website, and use the NETbilling Site settings to have transaction results post to that script.

There are many ways to take advantage of this interface to add new features to their websites. For example, merchants can use Membership Update Mode to offer customers the chance to assign the same username and password for other websites managed through the NETbilling Gateway. The same technique could be used to offer membership upgrade that allows customers to access a complimentary site for a small additional fee and using the Membership Update Mode to facilitate these changes to their account.

The NETbilling online system is still available for the manual editing and updating of membership and rebilling information. The new NETbilling Membership Update Mode is specifically added for the automating of membership and rebilling management. The NETbilling Membership Update Mode can be used in conjunction with all methods of NETbilling payment, including Direct Mode, the Virtual Terminal, and the NETbilling Payment form.

All of the variables used in the creation and management of memberships and rebilling records can be reviewed and updated with the NETbilling Membership Upgrade Mode.

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

URL: https://secure.netbilling.com/gw/native/mupdate1.1

You can now alter membership records and rebilling records with a simple direct interface, similar to the interface used for processing transactions with NETbilling Direct 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 Membership Update Mode in order to process a Membership Updates. The following set of fields are used to control the request to mupdate1.1.

C_ACCOUNT
Contains your NETbilling account number and an optional site tag, separated with a colon. The site tag is REQUIRED if using C_MEMBER_LOGIN (below) to identify the member. Example: "123123123123:SITETAG"
C_MEMBER_ID
The 12-digit Membership ID assigned by NETbilling. You can look this up in the NETbilling admin system if you don't already have it stored. Either the Member ID or the Member Login is required to identify the target of the operation. Example: "321654123645"
C_MEMBER_LOGIN
The member's login name stored by NETbilling. You can look this up in the NETbilling admin system if you don't have it stored already. Either the Member ID or the Member Login is required to identify the target of the operation. Example: "bobthejanitor"
C_CONTROL_KEYWORD
The access control keyword definable in the NETbilling admin system (on the website config page). 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:
GET
Will return information on the membership/rebilling directly in a list of CGI-formatted parameters (detailed below).
SET
Will allow you to modify those same values, EXCEPT M_MEMBER_STATUS, and M_ADDITIONAL_SITES, as detailed below.
REFRESH
Causes the member's records to be automatically updated on your website via NETbilling's member control cgi. It tells the NETbilling server to post an immediate member refresh to your site.
CHANGE_STATUS
Change status in M_MEMBER_STATUS (C_WRITABLE_FIELDS not necessary when using this mode)
STOP_RECURRING
Stops recurring billing
START_RECURRING
Restarts a stopped recurring billing
ADD_SITES
Include additional sites (M_ADDITIONAL_SITES) this member belongs to. Note that if any invalid site tags are provided the system will not make any changes, even if other site tags provided are valid. (C_WRITABLE_FIELDS not necessary when using this mode)
REM_SITES
Remove additional sites (M_ADDITIONAL_SITES) this member belongs to. Note that if any invalid site tags are provided, the system will not make any changes, even if other site tags provided are valid. (C_WRITABLE_FIELDS not necessary when using this mode)
C_WRITABLE_FIELDS
List of fields you wish to update when issuing a "SET" command. This list should be space or comma separated. Example: "M_MEMBER_PASSWORD M_MEMBER_LOGIN"

The following fields are returned when performing a "GET" or can be sent when using a "SET":

Recurring billing fields

R_RECURRING_SCHEDULE
Same as the Rebilling Period field in Direct Mode, this can be either an SQL Date expression or a simple number. If a date expression, it determines when the rebillings will fall due. If it's just a number, the rebillings will occur that many days apart. For instance, if you send "30", the customer will be rebilled every 30 days.
R_NEXT_DUE_DATE
Changes the next rebilling date. The date format is YYYY-MM-DD HH:MM:SS. Example: "2001-08-01" (The HH:MM:SS is optional)
R_NEXT_AMOUNT
Sets the amount for the next rebilling only. After that it will return to the normal rebill amount. Example: "19.95"
R_RECURRING_AMOUNT
Changes the regular rebilling amount (does not include the next rebilling amount - see R_NEXT_AMOUNT). Example: "29.95"
R_PERIODS_REMAINING
Changes the number of rebilling periods left before the membership is canceled and the user has to sign up again to start billing. Passing a null string will cause infinite rebillings. Example: "12"
R_TEMPLATE_CARD_NUMBER
Get-only field. Use R_TEMPLATE_TRANS_ID for set/update. Last digits of card number. Example: "xxxxxxxxxxxx6390"
R_TEMPLATE_CARD_ISSUER
Get-only field. This is the card issuer (VISA, MC, AMEX, etc.) of the recurring billing template card.
R_TEMPLATE_TRANS_ID
The 12-digit transaction ID used as a template for recurring transactions. The cardnumber, billing address, expiration date, etc. of future recurring transactions are sourced from this record. The transaction must exist in your account. Example: "837562749184"
R_TEMPLATE_TRANS_PROCESSOR
Get-only field. The processor originally used to authorize the template transaction.

Membership Fields

M_MEMBER_EMAIL
The member's e-mail address. Example: "support@netbilling.com"
M_MEMBER_PASSWORD
The member's password. Example: "hh34i9"
M_MEMBER_LOGIN
The member's login name. Example: "bobthejanitor"
M_EXPIRATION_DATE
Date of the membership expiration. The date format is YYYY-MM-DD HH:MM:SS. Example: "2001-08-01" (The HH:MM:SS is optional)
M_ADDITIONAL_SITES
Additional sites can be returned for a GET but not set using SET. If you wish to provide member access to additional sites, or remove a member's access to additional sites, use the ADD_SITES or REM_SITES commands, respectively. When an ADD_SITES or REM_SITES command is used M_ADDITIONAL_SITES should be passed as a space separated list of additional site tags for this member to belong to or to be removed from. Example: "SITE1 SITE2 MYSITE"
M_MEMBER_STATUS
Statuses can be returned for a GET but not set using SET. If you wish to change a member's status use the CHANGE_STATUS command. Only certain statuses can be set using CHANGE_STATUS
ACTIVE
Account active (can be used with CHANGE_STATUS)
DISABLED
Account manually disabled (can be used with CHANGE_STATUS)
PENDING
Member added, no payment made yet
EXPIRED
Has finished all rebillings and is no longer valid
ACTIVE/R
Active, but will switch to RESIGNED at next rebill date (This status occurs when a user self-cancels) (can be used with CHANGE_STATUS)
M_SIGNUP_TRANS_ID
Get-only field. The transaction ID of the original membership signup. This may be different from R_TEMPLATE_TRANS_ID.
M_MEMBER_ID
Get-only field. The 12-digit membership ID.