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.
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.
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.
- 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"
- 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"
- 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"
- 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"
- Tells the script what action to perform, as follows:
- Will return information on the membership/rebilling directly in a list of CGI-formatted parameters (detailed below).
- Will allow you to modify those same values, EXCEPT M_MEMBER_STATUS, and M_ADDITIONAL_SITES, as detailed below.
- 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 in M_MEMBER_STATUS (C_WRITABLE_FIELDS not necessary when using this mode)
- Stops recurring billing
- Restarts a stopped recurring billing
- 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)
- 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)
- 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
- 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.
- 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)
- Sets the amount for the next rebilling only. After that it will return to the normal rebill amount. Example: "19.95"
- Changes the regular rebilling amount (does not include the next rebilling amount - see R_NEXT_AMOUNT). Example: "29.95"
- 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"
- Get-only field. Use R_TEMPLATE_TRANS_ID for set/update. Last digits of card number. Example: "xxxxxxxxxxxx6390"
- Get-only field. This is the card issuer (VISA, MC, AMEX, etc.) of the recurring billing template card.
- 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"
- Get-only field. The processor originally used to authorize the template transaction.
- The member's e-mail address. Example: "email@example.com"
- The member's password. Example: "hh34i9"
- The member's login name. Example: "bobthejanitor"
- 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)
- 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"
- 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
- Account active (can be used with CHANGE_STATUS)
- Account manually disabled (can be used with CHANGE_STATUS)
- Member added, no payment made yet
- Has finished all rebillings and is no longer valid
- Active, but will switch to RESIGNED at next rebill date (This status occurs when a user self-cancels) (can be used with CHANGE_STATUS)
- Get-only field. The transaction ID of the original membership signup. This may be different from R_TEMPLATE_TRANS_ID.
- Get-only field. The 12-digit membership ID.