There are three major ways to process a payment with the NETbilling Gateway.
First, the Virtual Terminal within our admin system allows you to process a credit card order taken by phone, refund or void previous charges, and allows you to selectively override our fraud controls. It is accessible to merchants but not to customers, as it requires being logged into our admin system.
Second, there is the Payment Form. This interface is the most intuitive to provide to your customers. The customer is redirected from your website to a customizable payment form on the NETbilling Gateway's secure servers, which collects the credit card and address information for you and displays a receipt to the customer, then redirects them back to a specified url (typically on your web site). The payment form is completely customizable, down to including your own logo on the form, selectable background colors to match your website's look and feel, and the ability to control which fields are displayed and whether they are optional or required. It's even possible to collect all the data in a form on your own website and pass it to the NETbilling Gateway's payment form along with an extra option that will cause the NETbilling Gateway to process the transaction and then send the customer straight back to your site -- they never need to see the NETbilling Gateway's payment form at all. Several shopping carts use the NETbilling Gateway's Payment Form to accomplish their transaction processing.
Finally, there is Direct Mode. Direct Mode is for merchants who need to have complete control over the transaction. Using Direct Mode, the customer never even gets directed to the NETbilling Gateway's site; the transaction is sent to the NETbilling Gateway from the back end of the merchant's server. This leaves the merchant with the ability to completely customize the payment process for their specific needs. Unfortunately, this configurability comes at the price of requiring knowledge of sockets programming for your web server. Many merchants need to hire a programmer to effectively utilize Direct Mode. Further documentation on Direct Mode can be found under Documentation - Developer Docs - Direct Mode.
This document is concerned with the Payment Form, its setup and use, and all the options that are also common to the other forms of payment, such as membership signups and rebillings.
Those who are familiar with online transaction processing and web coding may wish to skip directly to the appendices, where the URLs to post to as well as the field names are listed.
The NETbilling Gateway's robust transaction processing engine has many extras that make it more than just a simple swipe terminal. Here we'll examine some of them by looking at the process of making a payment with the Payment Form.
To begin, a customer will choose products or subscriptions to purchase from your website, or shopping cart if you have one. If you have only a few products to sell, the NETbilling Gateway's admin system includes a Button Editor (Setup -> Button Editor) that will help you generate the proper HTML code to accept a payment in a specific amount. These buttons can be put on a page on your site and clicked on by the customer to be sent to our Payment Form, where we will collect the customer's payment information. Alternatively, you can create an HTML form of your own, collecting any information from the customer that you like. If this information duplicates the information requested on the Payment Form, then you can pass it along with the customer to the Form and it will be automatically entered into the Form, or if you collect all the information requested by the Form, you can pass it all and have the Form not display at all. In either case, once the customer has filled out any information requested by your site, you use an HTML form POST to send the customer, and any information, to the NETbilling Gateway's Payment Form. You can send this information securely by encrypting it using the Order Integrity feature of the Payment Form, essentially an MD5 checksum of the transaction information. If you are unfamiliar with MD5, don't worry; the Button Editor can set it up for you automatically, and the process of setting up Order Integrity yourself is described later in this document.
At this point, if the transaction is a membership signup or subscription, the customer is first prompted by the Payment Form to choose a username and password, unless you sent one along with the transaction information. Then the Payment Form requests the customer's credit card or checking and billing information, if it was not sent along with the transaction data. If the payment fails, the customer is returned to the Payment Form to try again. The number of tries is definable in the admin system (Security -> Risk Mgmt); if you want the first failure to take the customer to a web page instead of letting them try again, you can configure that as well. It's important to note that by default, the customer is returned to the Payment Form, so if you were sending all the transaction data and expecting the form to not be displayed at all, this will not be the behavior you expect. If payment fails too many times, then the customer is sent to a URL you have selected (Setup -> Website Config -> Giveup URL), with no payment made. If payment is made successfully, then the Payment Form displays a receipt to the customer, as well as e-mailing receipts to you as the merchant and to the customer. These receipt e-mails are also completely configurable (Setup -> Website Emails), and can remind a new customer of his username and password or just provide a simple "Thank you" and receipt. The system can also be configured to post the transaction data directly back to your site (Setup -> Website Config -> Postback CGI URL), so you don't need to rely on the customer's clicking through on the receipt page.
If the transaction is a membership or subscription, the the NETbilling Gateway servers can also be configured to connect to a CGI on your system and automatically post member information to your server, such as the member username and password (Setup -> Website Config -> Control CGI URL). If configured, this CGI will also receive a nightly post from the NETbilling Gateway, telling it which memberships have expired and which are still valid. While the NETbilling Gateway provides a Perl CGI script for the purpose of receiving these posts, it usually requires some programming knowledge to implement successfully.
Finally, the customer is directed back to a specified URL on your site. Transaction data will be sent along with the customer as a form POST or GET. If you have web coding experience, you can use this information to automatically control shipping or membership activation or anything else appropriate. Otherwise, the only indication you'll have of successful payments will be in the excellent reporting tools in the admin system or the receipt e-mail sent to the merchant with each transaction.
The NETbilling Gateway's Payment Form is highly configurable. Some of the options are specific to the Payment Form and some are available to any of the payment methods supported by the NETbilling Gateway's system.
To begin, configure your website information in the NETbilling Gateway's admin system. Under Site Tools, you'll find an option for Site Tags. Typically there will be a default site already set up for your account. Some customization will be necessary to set up a smooth payment system. Click on config next to the default website, or choose a short site tag, website name, and URL, and choose Add Site. Then click config next to the new site. The Site Tag is a mnemonic for your website, and will be passed along with the transaction data for each transaction. It's possible to set up multiple websites, and you can use the site tag to differentiate between payments for each site. There is no limit on the number of sites you can have configured in the NETbilling Gateway's system.
Most of the options under the site configuration screen are self explanatory. Here are some that may not be:
Return URL - This is the HTML or CGI page on your site that the customer is sent to after completing payment. The customer will be sent here with a POST or a GET containing the transaction information, so if you have the ability to code a CGI to handle this data, this is where you put it's URL.
GiveUp URL - This is where a customer is sent if payment is unsuccessful too many times. How many attempts are allowed is definable in the admin system under Security -> Risk Management.
Postback CGI URL - After processing each transaction, transaction data is sent to this CGI, if you have configured it. This is done because a customer failing to click-through on the Payment Form's receipt will never get directed back to your site, and the transaction data normally sent along with the customer will never get to your site. The Postback CGI allows a way around this, but requires some knowledge of web programming.
Return Method - This determines whether the transaction data is sent along with the customer as a POST or a GET. We strongly recommend POST, however if you are planning to collect all the transaction data before the transaction and not have the Payment Form displayed to the customer, the customer will be returned with a GET regardless of this setting. This is due to the way redirects are handled in HTTP.
Payment Form - We will be devoting a section to configuring the Payment Form specifically in a moment. In the meantime, you may wish to note which Payment Form the website is currently configured to use. You can have a different Payment Form setup for each Website.
Cancellation URL - You can copy this link onto your website, and a customer can click on it to automatically cancel his membership. This is a good reason to use the next option -- the Control CGI. See Appendix F for more information on Self Cancellation.
Control CGI URL - The URL of a CGI on your site that processes usernames and passwords for memberships. The NETbilling Gateway's servers will post a list of valid and expired usernames nightly, if you are processing memberships. The sample CGI available here is a Perl script that will most likely need some modification to work properly on your website.
Once you have configured the site to your satisfaction, choose Apply. At the top of this screen you will find the option to configure e-mail; this is where you go to choose which receipts get sent under what circumstances. You can design these receipts using the Email Editor under Setup in the menu. In the meantime, choose edit pmt form to go to the Form Editor.
This form has a number of options. You can define your own colors and logo to display on the Payment Form, as well as configure the names of the fields the form accepts. If you use a shipping cart, you can also choose pre-made forms to support the field names sent by that shopping cart. Remember that changing the field names may cause any old code (such as buttons made from the Button Editor) to fail until that code is updated to reflect the new field names.
You may notice that some of the fields duplicate information from the website config. If these fields are sent with the transaction, they will override what is set for the website.
If you are setting up your own payment form, the field names here are the ones you will POST to the NETbilling Gateway. You will need some minor HTML coding skills to do this.
If you haven't been into the NETbilling Gateway admin system before, you may want to check out and configure some of the other options available, such as the options under Security in our menu. You'll also need to define your merchant account under the Credit Cards option under Setup.
Remember to choose Apply at the bottom of the screen when you are done configuring the system, or your changes will not be saved.
For each field name, you can choose whether the field is Required, Optional, Hidden, Display Only, or Not Used. The meanings of each setting are as follows:
Required: The parameter may or may not be passed in the initial CGI request. Regardless, a text field on our payment page will require the customer to input the correct value before the payment is processed. This is useful for most fields, such as the customer's name, shipping address, etc.
Optional: The parameter may or may not be passed in the initial CGI request. Regardless, a text field on our payment page will be displayed, with the default value set to whatever was passed from your system. The customer will not be required to input information into this field to continue.
Display Only: The parameter must be passed in the initial CGI request. The value you pass into our system will be displayed in a read-only text field. This is useful for things like your product description, which should be displayed to the customer for confirmation, but should not be edited by the customer.
Not Used: The parameter is not passed in the initial CGI request. The customer is not prompted for this field, and nothing is displayed on our payment page for this field. Be careful not to set important fields (e.g. the customer's Credit Card number) to this.
Hidden: The parameter is provided in the initial CGI request to our server, but is not displayed to the customer. This is useful for fields you can set in advance and don't need or want the customer to see, for instance, if your system generated an order ID for the transaction, you can pass it to us, defined as a hidden parameter, and it won't get displayed to the customer. When it is passed back to your system at the end of the transaction, you can use it to associate the success or failure of the payment with the customer.
All fields you pass into our payment page are passed back to the URL defined in your setup. This is EXTREMEMLY important! If you do not define this URL (in the Site Editor tool), then your system will not receive any information regarding customer payments. You can also choose to use the Ecom_Ezic_Fulfillment_ReturnURL field to allow the shopping cart to control the return URL specifically for each transaction. (If passing the return url as a field in the transaction, it will over-ride the default setting.)
You can define the field names used to return return-only fields the same way you defined the input fields, above. The most important ones to look at in your CGI are the Status Code and Transaction ID. The Status Code will be:
"I" (letter I) - Incomplete / Pending
These are transactions that are successful, but may fail at a later date, such as the case of an ACH transaction being approved, but then being denied later due to NSF.
"1" (number 1) - Approved / Good
This is a transaction that is approved and charged.
"R" - Refunded
This transaction has been refunded. It's extremely unlikely you will ever see this return code in this context, although you may see it when browsing old transactions in our database (via the Admin tools).
"T" - Ticket
This is returned when an Auth or AVS-Only transaction is good.
"F" - Failure
"0" (number 0) - Failure
The number zero '0' or the letter 'F' indicates that the transaction failed. A more detailed message will be available in the response msg field.
(any other codes)
Any other non-zero, non-null codes should be interpreted as success for compatibility with future response codes.
The Transaction ID represents the number we assign to the transaction in our database. You can use this number to look up the transaction status in our Admin tools.
For now, you can get off to a quick start with the Button Editor. The Button Editor will automatically generate for you the proper HTML code to send a transaction to the Payment Form. After creating a button, you can copy the code at the top of the screen to your website and it will make a button that the customer can click to be sent to the Payment Form you have defined. You can also try it yourself on the Button Editor screen by clicking the demo button that is generated.
All the options on the Button Maker screen should be self-explanatory after a brief discussion of the transaction types allowed by the NETbilling Gateway.
The NETbilling Gateway's payment system supports sales, auth/captures, voids, refunds, credits, and memberships and rebillings. Here's a brief run-down of each:
Voids, refunds, and credits are all handled roughly the same. If the original transaction has already been captured then a void will automatically become a refund, as voiding a captured transaction is not possible. Voids, refunds and credits are not supported by the Payment Form. You can issue these from the Virtual Terminal.
Sales are exactly what you'd expect - they take money from the customer's credit card in one easy step. However, because credit card processors do not decline transactions based on address verification information, a transaction that violates your AVS (address verification) settings will automatically be voided, causing two transactions (and two fees) instead of one. You can get around this by using auth/captures.
Auths are authorizations of the customer's credit card. They essentially reserve a certain amount of the customer's money, without actually taking it. This is the type of transaction you would use for a "Free Trial" membership - a one dollar auth on the customer's card with no capture ever will not take any money from the customer, but will make sure that the card is valid.
Captures are the partner of Auths. You perform a capture on a previous auth, and then the customer's credit card is actually debited. Note that auths are generally valid for only a few days, and trying to capture after that may fail. While an auth can be run from the payment form, you must log into the admin system and look up the transaction (Main -> Find Trans) to perform a capture.
When you process a sale, it can be processed as either a sale as described above, or an auth with an automatic capture a few minutes later. This is configured from the Credit Card screen under Setup. This is allowed so that transactions that fail on AVS won't require a void to be automatically issued; if a sale is processed as an auth/capture, and fails on AVS, it will simply never be captured, meaning you get charged for one transaction, instead of two (sale/void) when using sales. The downside to this is that you get charged twice for successful transactions, once for the auth and once for the capture. Which option is best for you largely depends on how many AVS and CVV2 declines you receive.
In addition, when processing an auth or a sale, you can specify that the transaction is a membership signup or a rebilling. All rebillings require membership signups, but not all memberships require rebilling. In other words, to do a rebilling without a membership, you must specify a bogus membership username and password.
When processing a membership, you specify how long the membership is valid for. At the end of this period is when the first rebilling occurs, if any. So you can define a 'free trial' membership with automatic rebilling at a different rate by sending an auth (no charge) transaction with membership duration equivalent to your free trial, and then specify rebillings monthly at your usual rate. The initial transaction will only be an auth, but the rebillings will be sales.
Although your system can submit its information via a SSL (https://) connection, this alone is not enough to ensure security. A knowledgeable user may try to get free products or services from your company by changing the information submitted to our system. It's a relatively simple matter to copy the HTML source of your shopping cart's submittal page, then instead of submitting the correct price for your product, submit a lower (or $1.00) price.
Fortunately, we have a method for preventing this sort of attack. We use a crypto-hash function to ensure the data has not been tampered with between your system and ours. It's based on MD5, a strong cryptographic hashing algorithm developed by RSA Data Security, Inc.
To make optimal use of this feature, you should be familiar with basic CGI programming. You can still use this feature even if you don't have programming experience.
To begin with, you need to decide which fields are important, and should be protected. Generally, this would be the price of the product, your product ID number (if any) and so on. Be careful to make sure that any fields you apply crypto-hashing to are not set to "Required" or "Optional" in our system; if the user is allowed to change the values of these items, even within our system, it may be interpreted as an attack. If you do rebillings and member signups, you may want to include the related rebilling prices information, as well. You have to choose at least TWO fields. Crypto-Hash is unreliable when used on only one field, and the system will not accept it.
Next, you need to know your account's Crypto-hash Key. This is the Key your system will use to encode the crypto-hash value you will be sending to our system. This can be found on the Crypto-hash screen in our Admin tools.
It is VERY important that this number is kept confidential. If anyone gets access to the crypto-hash key, they can break into the system just as easily as if you weren't using it. If you believe your key has been compromised, return to the setup page and generate a new one immediately! Then remember to update any CGI scripts or pre-created MD5 sums (more on that below) to reflect the new key value.
Now, the next (and final) step will depend on how you are configuring your own web server. You have two options. If you are capable of CGI programming, then we strongly recommend you write a CGI script to compute the MD5 crypto-hash "on the fly." That way, you can encrypt dynamic fields, and if you have to change your crypto key, you can do so easily. The other option is to precompiled the MD5 sums of certain fields in advance, and simply store them in your HTML code. The disadvantage to that is if you have to change any of the information being encoded, including the key itself, you have to recompute all affected MD5 sums. For instance, if you change your prices on your products -- and the price should ALWAYS be part of the crypto-hash -- then you'll have to recompute the MD5 sums before allowing any new transactions.
Another bonus to using CGI programming to connect to our system is that you also receive a crypto-hash on return from our system. The return crypto-hash works exactly the same as the one that you sent to the system, except that it includes the additional Transaction ID and Status Code fields. These fields are added after your crypto-key and before all the fields you specified to be hashed.
The field in our spec called, "Ecom_Ezic_Security_HashFields" (unless you've renamed it using the Form Editor) is the space- separated list of fields you are crypto-hashing. For instance, if you wanted to include the price and product description, you would put the following into the "Ecom_Ezic_Security_HashFields" field (not including quotes): "Ecom_Cost_Total Ecom_Receipt_Description"
Note that the VALUES of these fields are not included. Only the field NAMES are specified in "Ecom_Ezic_Security_HashFields". The order of these field names is important. When you compute the MD5 Crypto-hash value, you MUST include the field values in the same order you list the field names here.
Now you compute the actual MD5 value based on your field values. To do this, we first concatenate the field values into a single string. For instance, if we continue the example above, and your product price is $29.95, and the product description is "T-shirt #535", you would concatenate them to make "29.95T-shirt #535". Again, of course, without the quote marks. Finally, you compute the MD5 sum of that together with your crypto-key you got from our system. If your crypto-key was "NgSZQOgwFXNBCcHRuTBL" then your final string would be: "NgSZQOgwFXNBCcHRuTBL29.95T-shirt #535".
Here's the Perl code to compute the Crypto-hash:
Here's how to do it from a Unix command-line:
(output: d6953dc6c8750a7f06b0ae4d0a94cbb5)
Of course, you use the former (or something similar) for CGI programming, and the later to generate the values by hand and then hard-code them into your site.
Simply take your computed crypto-hash value, now, and pass it along with the transaction, in the field "Ecom_Ezic_Security_HashValue_MD5".
When the transaction is returned to you, if you have chosen CGI as your implementation, you can verify that the transaction was not tampered with on the return side, as well. Those of you who are HTML-based need not worry; the worst a hacker can do on the return end is make you think the transaction succeeded until you check the logs on our system, which will always be correct.
The return crypto-hash value is stored in the Ecom_Ezic_ProofOfPurchase_MD5 field. The crypto-hash is computed exactly as described above, using the fields you specified in your request. EXCEPT: The Ecom_Ezic_Response_TransactionID and Ecom_Ezic_Response_StatusCode fields are computed into the crypto-hash, after your key value, but before the additional fields you specified.
NOTE: You must still pass the plaintext (non-encoded) keys and values as normal. Our system will compare them to the crypto-hash to determine whether any tampering has occurred.
The transaction data is to be sent to The NETbilling Gateway's server as a standard form POST. If you aren't familiar with HTML, check the Button Editor for an example of how to do this.
Memberships and Rebillings POST to:
https://secure.netbilling.com/gw/native/join2.2b
and set your Fulfillment Module URL to:
https://secure.netbilling.com/gw/native/interactive2.2
All plain sales and auths POST directly to:
https://secure.netbilling.com/gw/native/interactive2.2
For Authorize.Net compatibility, POST to:
https://secure.netbilling.com/gw/native/interactive2.2?x_Login
Note! The first parameter after the '?' identifies the name of the CGI parameter containing the the NETbilling Gateway account id and site tag. "?x_Login" is required for AuthorizeNet compatibility mode, native mode does not require this.
These are the DEFAULT Field Names and Requisite Options used by our system. If you change the field names, be sure you use the corresponding new names when posting information to our system!
| Requisite Option | Definition |
| R | required |
| O | optional |
| H | hidden (implied optional) |
| D | display only (non interactive) |
| N | dont collect |
Below are the billing address information fields (used for address verification)
| Default Field Name | Length | Requisite Option |
| Ecom_BillTo_Postal_Name_First | 15 | R |
| Ecom_BillTo_Postal_Name_Last | 15 | R |
| Ecom_BillTo_Postal_Street_Line1 | 20 | R |
| Ecom_BillTo_Postal_Street_Line2 | 20 | O |
| Ecom_BillTo_Postal_City | 22 | R |
| Ecom_BillTo_Postal_StateProv | 2 | R |
| Ecom_BillTo_Postal_PostalCode | 14 | R |
| Ecom_BillTo_Postal_CountryCode | 2 | R |
| Ecom_BillTo_Telecom_Phone_Number | 10 | O |
| Ecom_BillTo_Online_Email | 40 | R |
Below are the shipping address information fields.
| Default Field Name | Length | Requisite Option |
| Ecom_ShipTo_Postal_Name_First | 15 | R |
| Ecom_ShipTo_Postal_Name_Last | 15 | R |
| Ecom_ShipTo_Postal_Street_Line1 | 20 | R |
| Ecom_ShipTo_Postal_Street_Line2 | 20 | O |
| Ecom_ShipTo_Postal_City | 22 | R |
| Ecom_ShipTo_Postal_StateProv | 2 | R |
| Ecom_ShipTo_Postal_PostalCode | 14 | R |
| Ecom_ShipTo_Postal_CountryCode | 2 | R |
| Ecom_ShipTo_Telecom_Phone_Number | 10 | O |
| Ecom_ShipTo_Online_Email | 40 | R |
These fields are for Credit-Card payments only. Even if set to REQUIRED, they will not be considered required if the actual payment type is ACH.
| Default Field Name | Length | Requisite Option |
| Ecom_Payment_Card_Type | 4 | O |
| Ecom_Payment_Card_Number | 19 | R |
| Ecom_Payment_Card_Verification | 4 | O |
| Ecom_Payment_Card_ExpDate_Month | 2 | R |
| Ecom_Payment_Card_ExpDate_Year | 4 | R |
These fields are for ACH payments only. Even if set to REQUIRED, they will not be considered required if the actual payment type is a Credit Card.
| Default Field Name | Requisite Option |
| Ecom_Payment_Bank_PayerBankName | R |
| Ecom_Payment_Bank_PayerRoutingNumber | R |
| Ecom_Payment_Bank_PayerAccountNumber | R |
| Ecom_Payment_Bank_PayerPhotoIDNumber | H |
| Ecom_Payment_Bank_PayerPhotoIDState | H |
| Ecom_Payment_Bank_PayerSSN | O |
Fields required for ECML conformance:
| Default Field Name | Length | Requisite Option |
| Ecom_ConsumerOrderID | 20 | H |
| Ecom_WalletID | 40 | H |
The remainder of the fields are Gateway-Specific extensions to the ECML spec. Notes are given after each field that needs explanation.
| Default Field Name | Requisite |
| Ecom_Ezic_AccountAndSitetag | Always Required |
This is your account number and Sitetag, separated with a :. Example: 99998980029:THATSITE This tag is always required; our system uses it to associate the purchase with the proper site and payment form template.
| Default Field Name | Requisite |
| Ecom_Cost_Total | R |
The total cost of the sale/signup. This is how much the CC or ACH account will be charged for. PLEASE include this field in your Crypto-hash! (See above)
| Default Field Name | Requisite Option |
| Ecom_Cost_Tax | O |
The sales tax amount, if any. This is NOT added to the Total amount; the Total amount is the total amount.
| Default Field Name | Length | Requisite Option |
| Ecom_Receipt_Description | 4000 | R |
Up to 4000 characters of text to be displayed on the payment page. Should include a description of the products/services the customer is paying for, for confirmation.
| Default Field Name | Length | Requisite Option |
| Ecom_Ezic_Misc_Information | 4000 | O |
This field is typically used to allow the purchaser to send some information back to the merchant. If the purchaser fills this field out on our payment form, it is included in the receipt e-mails sent to the merchant and the purchaser.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Fulfillment_Module | O |
This allows you to choose a "Fulfillment Module." The Fulfillment Module can handle post-payment functions, such as member signup. In version 2.2, the only valid Fulfillment Module is "join2.2b" which allows member signups and rebillings. Note if this is empty, the sale will only be a sale, so if you're doing member signups, be sure to include this field.
| Default Field Name | Requisite Option |
| Ezic_HideForm | O |
If you pass a TRUE (non-blank, non-zero) value in this field, our system will attempt to process the transaction without prompting the customer for any information. If you have passed all required fields in the initial request, no payment form will be displayed and the system will skip directly to printing a redirect back to your return CGI url.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Fulfillment_ReturnURL | O |
If provided, this URL is where the customer is sent after a successful transaction. Note that this overrides the setting in your website config.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Fulfillment_GiveUpURL | O |
If provided, this URL is where the customer is sent after a failed transaction. Note that this overrides the setting in your website config.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Payment_AuthorizationType | R |
This field determines whether you are processing a sale or an auth. Acceptable values are 'SALE' and 'PREAUTH' (without the quotes, of course).
Crypto-Hash Fields
These are the fields used by the Crypto-Hash feature.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Security_HashValue_MD5 | O |
This is the computed hash code. See the above Crypto-Hash section for details.
| Default Field Name | Requisite Option |
| Ecom_Ezic_Security_HashFields | O |
This field contains a space-separated list of fields included in the hash value, above. Note that on return, these fields are added AFTER the ID and Status fields.
| Default Field Name | Requisite Option |
| Ecom_Ezic_ProofOfPurchase_MD5 | O |
This is the return hash code. It's computed the same as the Security_HashValue_MD5 that you send with your transaction data, except the TransactionID and Transaction Status fields are prepended before the list of fields specified in Security Hashfields. You can use this to be sure that hackers don't change the data returned to you.
Response Fields
These are the fields that the Native Interface will post back to your CGI URL. You may optionally set the encoding of these fields to support various shopping-carts. See the Form Editor in your Setup for details.
Ecom_Ezic_Response_StatusCode
Contains a single-character response indicating the success or failure of the transaction. Here's a table to help you: I = Incomplete. ACH transactions return this when they are successful, but have not cleared the bank yet (it takes three days to clear). Also Credit Cards that are approved, but have yet to close in batch. Should be interpreted as SUCCESS.
1 = Approved, final. This transaction is approved and the money has changed hands. Should be interpreted as SUCCESS.
I = Ticket. This is returned for AVS-ONLY and AUTH types of transactions. Should be interpreted as SUCCESS.
0 = '0' (zero) and 'F' should be interpreted as a decline / failure of the transaction.
D = Duplicate submission. Already approved successfully.
Any other value = Success. Any other returned value should be interpreted as success for compatibility with future versions.
Ecom_Ezic_Response_AuthCode
This is a six character string response from the Credit Card processor.
Ecom_Ezic_Response_AuthMessage
Plain text message interpreting the status of this transaction. Usually something like, "Successful," or "Failed, BAD AVS." A useful text description of the problem will be included for all failures.
Ecom_Ezic_Response_TransactionID
The NETbilling Gateway's 12-digit Transaction ID. Can be used to track the transaction in the Admin tools.
Ecom_Ezic_Response_Card_AVSCode
AVS Response for Credit Card transactions.
Ecom_Ezic_Response_Card_VerificationCode
CVV2 Response for Credit Card transactions.
Ecom_Ezic_Response_IssueDate
Date transaction was issued on. Should always be today's date.
Other Fields
Ecom_SchemaVersion
Unused. Included for ECML compliance.
Ecom_TransactionComplete
Unused. Included for ECML compliance.
Ecom_Ezic_Response_StatusSubCode
Unused. Currently returns same value as Ecom_Ezic_TransactionStatus, however this may change in future versions.
Ecom_UserData_
This field is a prefix with which you can make up your own fields that will be stored in the The NETbilling Gateway database and can be displayed on the automated receipts. For instance, if you assign a number to each customer, you could pass that in a field called Ecom_UserData_CustomerNumber and it would be stored with the transaction on The NETbilling Gateway's machine, as well as being available to you to add to a receipt, and passed back to your system with the transaction data after the transaction is processed.
Join2.2b Fields
These are the fields that can be posted when you post to join2.2b and use interactive2.2 as your fulfillment module.
| Default Field Name | Requisite |
| Ecom_Ezic_Membership_UserName | R |
| Ecom_Ezic_Membership_PassWord | R |
The customer's choosen login name and password.
| Default Field Name | Requisite |
| .Verify_Password | R |
Note this field name begins with a period. This should be a duplicate of the Ecom_Ezic_Membership_PassWord field. Normally the NETbilling membership signup form will prompt to verify the password, and you should not send this field. Use it only if you are trying to bypass the signup form with a pre-selected password.
| Default Field Name | Requisite |
| Ecom_Ezic_Membership_Period | R |
This determines how long, in days, the membership is valid for. Remember, when performing a rebilling, the first rebilling does not occur until this initial membership period is over.
| Default Field Name | Requisite |
| Ecom_Ezic_Recurring_Period | O |
For rebillings, this determines how often to rebill. Can be an SQL date expression or a number of days.
| Default Field Name | Requisite |
| Ecom_Ezic_Recurring_Amount | O |
The amount to rebill on each rebilling.
| Default Field Name | Requisite |
| Ecom_Ezic_Recurring_Count | O |
The number of rebillings to process. When the customer has been rebilled this many times his account is canceled and a new initial transaction must be processed to restart him.
| Default Field Name | Requisite |
| Ecom_Ezic_Recurring_Prorate | O |
Set this field to true to prorate the initial rebilling period. This only has any meaning if you are using an SQL date expression for the rebilling period instead of a raw number of days.
The 2.2 Native (Membership) Form is nearly identical to the 2.2 Native (E-Wallet) Form. The primary difference is that the following Ship To fields are not required, because when purchasing a membership, there is generally nothing to ship to the user.
If you do ship goods to users who join your membership site, then you can, of course, change the option settings from "Not Used" to "Required" or "Optional".
More information about these fields and their usage can be found in Appendix B of this document.
Payment Form Mode A is Authorize.Net 3.0 compatible and is designed to accept postings from shopping carts and websites designed with this specification.
Mode A is recommended for users who have an existing shopping cart or website designed for the Authorize.Net 3.0 specification only. If you are building a website from scratch, we recommend the 2.2 Native (E-Wallet) mode. Mode A is not recommended for use with membership websites.
PLEASE NOTE: Unless you are an expert, we recommend that if you use Mode A that you use the default template without modification.
ALSO NOTE: Authorize.Net compatibility, POST to:
https://secure.netbilling.com/gw/native/interactive2.2?x_Login
Note! The first parameter after the '?' identifies the name of the CGI parameter containing the account id and site tag. "?x_Login" is required for AuthorizeNet compatibility mode, native mode does not require this.
For more on this feature see Appendix A.
Below is a list of all the field names in Mode A and their usage.
This section is only applicable to credit card processing
| Field Definition | Authorize.Net compatible field name |
| Card Expire Date Month | x_Exp_DateMM |
| Card Expire Date Year | x_Exp_DateYY |
| Card Number | x_Card_Num |
| Response Card Avs Code | x_avs_code |
This section is only applicable to electronic check processing
| Field Definition | Authorize.Net compatible field name |
| Bank Account Number | x_Bank_Acct_Num |
| Bank Name | x_Bank_Name |
| Bank Routing Number | x_Bank_ABA_Code |
This section applies to the customer billing address
| Field Definition | Authorize.Net compatible field name |
| Bill To City | x_City |
| Bill To Country | x_Country |
| Bill To Email | x_Email |
| Bill To First Name | x_First_Name |
| Bill To Last Name | x_Last_Name |
| Bill To Phone | x_Phone |
| Bill To State | x_State |
| Bill To Street Line1 | x_Address |
| Bill To Street Line2 | x_Company |
| Bill To Zip Code | x_Zip |
This section applies to the customer shipping address
| Field Definition | Authorize.Net compatible field name |
| Ship To City | x_Ship_To_City |
| Ship To Country | x_Ship_To_Country |
| Ship To Email | x_Ship_To_First_Name |
| Ship To First Name | x_Ship_To_Last_Name |
| Ship To Last Name | n/a |
| Ship To Phone | n/a |
| Ship To State | x_Ship_To_State |
| Ship To Street Line1 | x_Ship_To_Address |
| Ship To Street Line2 | x_Ship_To_Company |
| Ship To Zip Code | x_Ship_To_Zip |
This section defines how response codes are encoded
| Field Definition | Authorize.Net compatible field name |
| Response Auth Code | x_auth_code |
| Response Auth Message | x_response_reason_text |
| Response Card Avs Code | x_avs_code |
| Response Status Code | x_response_code |
| Response Transaction Id | x_trans_id |
| Request Auth Type | x_Type |
| Return Method | x_Receipt_Link_Method |
| Return URL | x_Receipt_Link_URL |
This section is miscellaneous information
| Field Definition | Authorize.Net compatible field name |
| Tax Amount | x_Tax |
| Total Amount | x_Amount |
| Consumer Order Id | x_Invoice_Num |
| Description | x_Description |
Below is a listing of all the field names for Mode A and their Corresponding 2.2 Native (E-Wallet) field names. If there is a blank line under the Mode A column, there is no equivalent field name in the Authorize.Net 3.0 specification.
For a full explanation on each of these fields uses, please refer to the corresponding 2.2 Native (E-Wallet) field name description in Appendix B of this document.
| Authorize.Net compatible field name | Native NETbilling (E-Wallet) field name |
| x_Exp_DateMM | Ecom_Payment_Card_ExpDate_Month |
| x_Exp_DateYY | Ecom_Payment_Card_ExpDate_Year |
| x_Card_Num | Ecom_Payment_Card_Number |
| Ecom_Payment_Card_Type | |
| x_avs_code | Ecom_Payment_Card_Verification |
| Ecom_Ezic_Response_Card_AVSCode | |
| cvv2_result | Ecom_Ezic_Response_Card_VerificationCode |
| x_Bank_Acct_Num | Ecom_Payment_Bank_PayerAccountNumber |
| x_Bank_Name | Ecom_Payment_Bank_PayerBankName |
| Ecom_Payment_Bank_PayerPhotoIDNumber | |
| Ecom_Payment_Bank_PayerPhotoIDState | |
| x_Bank_ABA_Code | Ecom_Payment_Bank_PayerRoutingNumber |
| Ecom_Payment_Bank_PayerSSN | |
| x_City | Ecom_BillTo_Postal_City |
| x_Country | Ecom_BillTo_Postal_CountryCode |
| x_Email | Ecom_BillTo_Online_Email |
| x_First_Name | Ecom_BillTo_Postal_Name_First |
| x_Last_Name | Ecom_BillTo_Postal_Name_Last |
| x_Phone | Ecom_BillTo_Telecom_Phone_Number |
| x_State | Ecom_BillTo_Postal_StateProv |
| x_Address | Ecom_BillTo_Postal_Street_Line1 |
| x_Company | Ecom_BillTo_Postal_Street_Line2 |
| x_Zip | Ecom_BillTo_Postal_PostalCode |
| x_Ship_To_City | Ecom_ShipTo_Postal_City |
| x_Ship_To_Country | Ecom_ShipTo_Postal_CountryCode |
| Ecom_ShipTo_Online_Email | |
| x_Ship_To_First_Name | Ecom_ShipTo_Postal_Name_First |
| x_Ship_To_Last_Name | Ecom_ShipTo_Postal_Name_Last |
| Ecom_ShipTo_Telecom_Phone_Number | |
| x_Ship_To_State | Ecom_ShipTo_Postal_StateProv |
| x_Ship_To_Address | Ecom_ShipTo_Postal_Street_Line1 |
| x_Ship_To_Company | Ecom_ShipTo_Postal_Street_Line2 |
| x_Ship_To_Zip | Ecom_ShipTo_Postal_PostalCode |
| x_auth_code | Ecom_Ezic_Response_AuthCode |
| x_response_reason_text | Ecom_Ezic_Response_AuthMessage |
| x_avs_code | Ecom_Ezic_Response_Card_AVSCode |
| Ecom_Ezic_Response_Card_VerificationCode | |
| Ecom_Ezic_Response_IssueDate | |
| x_response_code | Ecom_Ezic_Response_StatusCode |
| Ecom_Ezic_Response_StatusSubCode | |
| x_trans_id | Ecom_Ezic_Response_TransactionID |
| x_Type | Ecom_Ezic_Payment_AuthorizationType |
| Ecom_UserData_ | |
| x_Receipt_Link_Method | Ecom_Ezic_Fulfillment_ReturnMethod |
| x_Receipt_Link_URL | Ecom_Ezic_Fulfillment_ReturnURL |
| Ecom_Ezic_Misc_Information | |
| x_Tax | Ecom_Cost_Tax |
| x_Amount | Ecom_Cost_Total |
| Ecom_WalletID | |
| x_Invoice_Num | Ecom_ConsumerOrderID |
| x_Description | Ecom_Receipt_Description |
The following fields have special encoding and they must be toggled to "Authorize Net" in order for them to function correctly with Authorize.Net compatible shopping carts:
x_response_code
x_Type
x_Receipt_Link_Method
Payment Form Mode V is Verisign compatible and is designed to accept postings from shopping carts and websites designed with this specification.
Mode V is recommended for users who have an existing shopping cart or website designed for the Verisign specification only. If you are building a website from scratch, we recommend the 2.2 Native (E-Wallet) mode. Mode V is not recommended for use with membership websites.
PLEASE NOTE: Unless you are an expert, we recommend that if you use Mode V that you use the default template without modification.
Below is a list of all the field names in Mode V and their usage.
This section is only applicable to credit card processing
| Field Definition | Verisign compatible field name |
| Card Expire Date Month | EXPDATEMM |
| Card Expire Date Year | EXPDATEYY |
| Card Number | CARDNUM |
| Card Type | n/a |
| Card Verification Value | n/a |
| Response Card Avs Code | AVSDATA |
| Response Card Ver Code | n/a |
This section is only applicable to electronic check processing
| Field Definition | Verisign compatible field name |
| Bank Account Number | n/a |
| Bank Name | n/a |
| Bank Photo Id # | DLNUM |
| Bank Photo Id State | STATEOFDL |
| Bank Routing Number | n/a |
| Bank Social Sec # | n/a |
This section applies to the customer billing address
| Field Definition | Verisign compatible field name |
| Bill To City | CITY |
| Bill To Country | COUNTRY |
| Bill To Email | |
| Bill To First Name | NAME1 |
| Bill To Last Name | NAME2 |
| Bill To Phone | PHONE |
| Bill To State | STATE |
| Bill To Street Line1 | ADDRESS |
| Bill To Street Line2 | n/a |
| Bill To Zip Code | ZIP |
This section applies to the customer shipping address
| Field Definition | Verisign compatible field name |
| Ship To City | CITYTOSHIP |
| Ship To Country | COUNTRYTOSHIP |
| Ship To Email | EMAILTOSHIP |
| Ship To First Name | NAMETOSHIP1 |
| Ship To Last Name | NAMETOSHIP2 |
| Ship To Phone | PHONETOSHIP |
| Ship To State | STATETOSHIP |
| Ship To Street Line1 | ADDRESSTOSHIP |
| Ship To Street Line2 | n/a |
| Ship To Zip Code | ZIPTOSHIP |
This section defines how response codes are encoded
| Field Definition | Verisign compatible field name |
| Response Auth Code | AUTHCODE |
| Response Auth Message | RESPMSG |
| Response Card Avs Code | AVSDATA |
| Response Card Ver Code | n/a |
| Response Issue Date | n/a |
| Response Status Code | RESULT |
| Response Status Sub Code | n/a |
| Response Transaction Id | PNREF |
| Request Auth Type | TYPE |
| Request User Data Prefix | USER |
| Return Method | n/a |
| Return URL | n/a |
This section is miscellaneous information
| Field Definition | Verisign compatible field name |
| Tax Amount | TAX |
| Total Amount | AMOUNT |
| Wallet Id | n/a |
| Consumer Order Id | n/a |
| Description | DESCRIPTION |
Below is a listing of all the field names for Mode V and their Corresponding 2.2 Native (E-Wallet) field names. If there is a blank line under the Mode V column, there is no equivalent field name in the Verisign specification.
For a full explanation on each of these fields uses, please refer to the corresponding 2.2 Native (E-Wallet) field name description in Appendix A of this document.
| Verisign compatible field name | Native NETbilling (E-Wallet) field name |
| EXPDATEMM | Ecom_Payment_Card_ExpDate_Month |
| EXPDATEYY | Ecom_Payment_Card_ExpDate_Year |
| CARDNUM | Ecom_Payment_Card_Number |
| Ecom_Payment_Card_Type | |
| Ecom_Payment_Card_Verification | |
| Ecom_Ezic_Response_Card_AVSCode | |
| Ecom_Ezic_Response_Card_VerificationCode | |
| Ecom_Payment_Bank_PayerAccountNumber | |
| Ecom_Payment_Bank_PayerBankName | |
| DLNUM | Ecom_Payment_Bank_PayerPhotoIDNumber |
| STATEOFDL | Ecom_Payment_Bank_PayerPhotoIDState |
| Ecom_Payment_Bank_PayerRoutingNumber | |
| Ecom_Payment_Bank_PayerSSN | |
| CITY | Ecom_BillTo_Postal_City |
| COUNTRY | Ecom_BillTo_Postal_CountryCode |
| Ecom_BillTo_Online_Email | |
| NAME1 | Ecom_BillTo_Postal_Name_First |
| NAME2 | Ecom_BillTo_Postal_Name_Last |
| PHONE | Ecom_BillTo_Telecom_Phone_Number |
| STATE | Ecom_BillTo_Postal_StateProv |
| ADDRESS | Ecom_BillTo_Postal_Street_Line1 |
| Ecom_BillTo_Postal_Street_Line2 | |
| ZIP | Ecom_BillTo_Postal_PostalCode |
| CITYTOSHIP | Ecom_ShipTo_Postal_City |
| COUNTRYTOSHIP | Ecom_ShipTo_Postal_CountryCode |
| EMAILTOSHIP | Ecom_ShipTo_Online_Email |
| NAMETOSHIP1 | Ecom_ShipTo_Postal_Name_First |
| NAMETOSHIP2 | Ecom_ShipTo_Postal_Name_Last |
| PHONETOSHIP | Ecom_ShipTo_Telecom_Phone_Number |
| STATETOSHIP | Ecom_ShipTo_Postal_StateProv |
| ADDRESSTOSHIP | Ecom_ShipTo_Postal_Street_Line1 |
| Ecom_ShipTo_Postal_Street_Line2 | |
| ZIPTOSHIP | Ecom_ShipTo_Postal_PostalCode |
| AUTHCODE | Ecom_Ezic_Response_AuthCode |
| RESPMSG | Ecom_Ezic_Response_AuthMessage |
| AVSDATA | Ecom_Ezic_Response_Card_AVSCode |
| Ecom_Ezic_Response_Card_VerificationCode | |
| Ecom_Ezic_Response_IssueDate | |
| RESULT | Ecom_Ezic_Response_StatusCode |
| Ecom_Ezic_Response_StatusSubCode | |
| PNREF | Ecom_Ezic_Response_TransactionID |
| TYPE | Ecom_Ezic_Payment_AuthorizationType |
| USER | Ecom_UserData_ |
| Ecom_Ezic_Fulfillment_ReturnMethod | |
| Ecom_Ezic_Fulfillment_ReturnURL | |
| Ecom_Ezic_Misc_Information | |
| TAX | Ecom_Cost_Tax |
| AMOUNT | Ecom_Cost_Total |
| Ecom_WalletID | |
| Ecom_ConsumerOrderID | |
| DESCRIPTION | Ecom_Receipt_Description |
The following fields have special encoding and they must be toggled to "Verisign/Signio" in order for them to function correctly:
AVSDATA - This code is toggled in two different places: Response Card Avs Code under card processing Response Card Avs Code under the encoding section
RESULT
TYPE
Your members can cancel their membership or change some of their membership information themselves with the NETbilling Self-Cancellation Page. Through a simple-to-use interface, members can look up their current membership and either cancel service or change contact information. The Self-Cancellation Page will greatly reduce the number of possible chargebacks on your account.
You can find the URL to the Self-Cancellation Page by visiting the Site Tags | Configuration page, under Site Tools, you'll find an option for Site Tags. Click on config next to the required site tag. Scroll down the page until you see CANCELLATION URL. To the right of this is an automatically generated generated Self-Cancellation Page link. Highlight and copy this URL Link to your website in a prominent place.
Once a customer has clicked on this Link, they will call up the Self-Cancellation Page which will request the following information:
User must enter at least three (3) of these items correctly to continue.
Click FIND MEMBER, and the system will quickly find the member and display their information. To the right, they will see in blue:
By clicking on the blue MAKE CHANGES link, another pop-up screen will appear showing their current Member information. The Member can make changes to their EMAIL and PASSWORD, and then click apply to save the changes.
By clicking on CANCEL MEMBERSHIP, another pop-up screen will appear, warning the Member that the cancellation will be final. When they click "OK", the Membership will be canceled and their rebillings will stop.
The merchant and the Member can (optionally) automatically receive an email when Self-Cancellation has been activated. Here's briefly how to assign emails to events and a description of the options on this page. For more information on configuring the email system, please refer to our complete email system documentation.