NETbilling has the most powerful Direct Mode payment interfaces available
in the gateway industry. These interfaces allow merchants to completely automate payment
processing. The Scriptable Reporting Interface is a Direct Mode style interface allowing
merchants to access their transaction and membership data in a machine parsable format
through an easy-to-use network API. This data can be used for a merchant's own statistical
monitoring or in conjunction with third party affiliate management software. All data is
stored in the Gateway system and shared according to stringent Visa PCI regulations.
This interface is intended to be used by merchants to develop their own software for monitoring transaction and membership data or to utilize third party affiliate management software to accomplish these tasks. As outlined below, the Scriptable Reporting Interface is actually divided into two separate interfaces for separately acquiring transaction and membership data.
This document outlines the technical specifications needed to take advantage of the Scriptable
Reporting Interface and is intended for a technical audience. Knowledge of HTTP standards is
assumed.
To make client implementation as simple as possible, the Scriptable Reporting Interface protocol is based on the standard HTTP protocol and SSL (HTTPS) encryption. Most modern languages have built in libraries that can be used to implement HTTP clients with very little effort.
A request is initiated by sending an HTTP POST to our host. The host will respond momentarily
with the resulting information on the same socket. All attribute-value pairs in the request should be
URL encoded,
just like a standard <form> POST from a browser. All response data will be returned in CSV format or text format.
The following host addresses should be used to access the Scriptable Reporting Interface:
| Host | Description |
|---|---|
| https://secure.netbilling.com/gw/reports/member1.4 | Member Reporting Interface |
| https://secure.netbilling.com/gw/reports/transaction1.4 | Transaction Reporting Interface |
The secure handling of an account's transaction and membership data is achieved through two separate security considerations. The primary security method comes in the form of a required list of authorized static client IP addresses. The management of such authorized IP addresses can be handled through the "Scriptable Reporting Interface" section of the "Access Security" page. Multiple addresses and/or entire subnets can be added to this approved listing to allow merchants to utilize this tool for both personal reporting usage as well as to grant access to this data for a 3rd party affiliate organization or multiple such entities. Proper management of approved IP addresses is the most important method for ensuring the protection of all membership and transaction data within an account.
The second method of security required to take advantage of these reporting interfaces comes in the form of providing a
list of approved access keywords for each site tag that is to be available for remote data access. The merchant has the
option of providing multiple keywords for each site tag to provide parallel access to separate reporting entities, and doing
so will ensure that access can easily be revoked for one specific reporting entity without affecting others.
This section will outline and explain all parameters recognized by the system relating to the Scriptable Reporting Interface
protocol as well as which of these are required for proper operation of each of the separate interfaces.
The following input parameters are necessary for proper operation of both the Member and Transaction Scriptable Reporting Interfaces.
| Parameter | Condition | Details |
|---|---|---|
| account_id | Required | The 12-digit gateway account ID from which data is to be extracted. |
| site_tag | Optional | This field specifies a particular site tag from which the data will be extracted. If this is not provided data from all site tags will be returned. This field can be specified multiple times to return data from several specific site tags. Examples of this can be found in sections 2.2 and 2.3 below. |
| authorization | Required | This field should contain the authorization keyword for the given site tag. These keywords can be managed from the Website Config page for the given site tag. This field can be specified multiple times with each request to provide authorization keywords for multiple site tags. Examples of this can be found in sections 2.2 and 2.3 below. |
The following input parameters are for use with the Member Reporting Interface (member1.4). Of the following
"after" fields at least one must be included for proper operation of the Member Reporting Interface, all others
are optional.
| Parameter | Condition | Details |
|---|---|---|
| expire_after | Required* | If used, only data for members who expired or would expire on or after the date specified by this field would be returned. |
| expire_before | Optional | If used, only data for members who expired or would expire before the date specified by this field would be returned. |
| transactions_after | Required* | If used, only data for members who had transaction data processed on or after the date specified by this field would be returned. |
| transactions_before | Optional | If used, only data for members who had transaction data processed before the date specified by this field would be returned. |
| changed_after | Required* | If used, only data for members whose last status change occurred on or after the date specified by this field would be returned. |
| changed_before | Optional | If used, only data for members whose last status change occurred before the date specified by this field would be returned. |
The following is an example of a typical HTTP POST request to the Member Reporting Interface for a single site tag:
POST /gw/reports/member1.4 HTTP/1.0 Host: secure.netbilling.com Content-Type: application/x-www-form-urlencoded Content-Length: 125 account_id=123456789012&site_tag=TEST&transactions_after=2006-12-30&transactions_before=2006-03-01&authorization=TEST_KEYWORD
The following is an example of a typical HTTP POST request to the Member Reporting Interface for multiple site tags with multiple access keywords:
POST /gw/reports/member1.4 HTTP/1.0 Host: secure.netbilling.com Content-Type: application/x-www-form-urlencoded Content-Length: 123 account_id=123456789012&site_tag=TEST1&site_tag=TEST2&expire_after=2006-12-30&authorization=TEST1_KW&authorization=TEST2_KW
The following input parameters are for use with the Transaction Reporting Interface (transaction1.4).
| Parameter | Condition | Details |
|---|---|---|
| transactions_after | Required1 | Transaction data issued on or after the date specified by this field would be returned. |
| transactions_before | Optional | If Used, transaction data issued before the date specified by this field would be returned. |
| disputes_after | Required1 | Download only NBCheck chargeback transactions having resulted from disputes by customer on or after specified date. |
| disputes_before | Optional | |
| returned_after | Required1 | Download only NBCheck transactions which were returned ("bounced") on or after specified date. This can be combined with transactions_after / transactions_before or used by itself. |
| returned_before | Optional | |
| charged_back_after | Required1 | Download only transactions reported by ChargeBack LookoutTM on or after specified date. Both ChargeBacks and Retrieval Requests can be downloaded. This may be combined with transactions_after / transactions_before or used by itself. Newly reported chargebacks, even when back-dated, will not be missed as the query is based on the reporting date in the system, not the bank's posting date. See dispute_report_date. |
| charged_back_before | Optional |
The following is an example of a typical HTTP POST request to the Transaction Reporting Interface for a single site tag:
POST /gw/reports/transaction1.4 HTTP/1.0
Host: secure.netbilling.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 94
account_id=200274083904&site_tag=TEST&transactions_after=2006-12-30&authorization=TEST_KEYWORD
The following is an example of a typical HTTP POST request to the Transaction Reporting Interface for multiple site tags with multiple access keywords:
POST /gw/reports/transaction1.4 HTTP/1.0
Host: secure.netbilling.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 136
account_id=200274083904&site_tag=TEST1&site_tag=TEST2&transactions_after=2006-12-30&authorization=TEST1_KW&authorization=TEST2_KW
This section will outline and explain all response fields provided by the Scriptable Reporting Interface. Data will be returned in CSV (text/x-comma-separated-values MIME type)
with field names provided on the first line of the response. All data is double quote (") enclosed. Any double-quotes within a data field will be removed to simplify parsing rather
than double quoted per the CSV standard. Responses will be guaranteed to never contain a newline-linefeed sequence except at the end of
each record. Future fields may be added or the field order changed. The client must consult the header line to determine the field order when parsing a response.
The following fields are those that will be returned following every successful request to the Member Reporting Interface.
| Field | Details |
|---|---|
| site_tag | The site tag the given member belongs to. |
| member_id | The unique 12-digit member ID identifying the given member. This ID can be used to directly link membership and transaction data. |
| member_status | The current status of the membership. This status will be one of the following:
"ACTIVE" - Member is active. "ACTIVE/R" - Member will automatically be "RESIGNED" at the next recurring billing date. "RESIGNED" - Member has resigned. "DISABLED" - Member has been disabled. "EXPIRED" - Member has expired. |
| previous_member_status | The membership status prior to the most recent status change. |
| status_change_date | The date (YYYY-MM-DD HH:MM:SS) when this member's status last changed. |
| member_user_name | The login name for the given member. Login names are unique to particular site tags and will also be unique across all site tags if configured that way in the "Website Config" for that site. |
| signup_date | The date (YYYY-MM-DD HH:MM:SS) the membership was created. |
| expire_date | The date (YYYY-MM-DD HH:MM:SS) the membership will expire or has already expired on. |
| email_address | The e-mail address associated with the given membership. |
| recurring_status | The current recurring billing status for the membership. This will typically be one of the following:
"RUNNING: OK" - Recurring billing is running as scheduled. "RUNNING: INVALID TEMPLATE ID" - Recurring billing is running but will fail at the next due date because the template transaction ID is invalid. "RUNNING: RETRYING FAILED ATTEMPT" - Recurring billing is running and will attempt to collect on a previous failed attempt at the next due date. "RUNNING: STOP AT NEXT DUE DATE" - Recurring billing is running but is scheduled to stop at the next due date. "STOPPED: OK" - Recurring billing is not running. "STOPPED: NO MORE PAY PERIODS" - Recurring billing is stopped and there are no pay periods remaining. "STOPPED: NO CREDIT CARD" - Recurring billing is stopped and no template transaction ID has been set. "STOPPED: INVALID TEMPLATE ID" - Recurring billing is stopped and the template transaction ID is invalid. "BROKEN: TOO MANY FAILURES" - Recurring billing has stopped because of too many failed transactions. "BROKEN: INVALID TEMPLATE ID" - Recurring billing has stopped because the template transaction ID is invalid. |
| recurring_next_date | The date (YYYY-MM-DD HH:MM:SS) scheduled for the next automatic recurring billing. |
| recurring_period | The recurring billing schedule. This will either be a number of days or a special period expression. A special period expression would be an Oracle style date expression such as "last_day(sysdate)+1" for the first day of every month or "add_months(sysdate,1)" for the same day every month. |
| recurring_periods_left | The number of recurring billing periods remaining. |
| recurring_amount | The normal dollar amount to be charged with each recurring billing. |
| next_recurring_amount | The dollar amount that will be charged to this customer at the next scheduled recurring billing. |
The following is an example of a typical request and response exchange for the Member Reporting Interface:
Request:
POST /gw/reports/member1.4 HTTP/1.0 Host: secure.netbilling.com Content-Type: application/x-www-form-urlencoded Content-Length: 88 account_id=123456789012&site_tag=TEST&expire_after=2004-01-01&authorization=TEST_KEYWORD
HTTP/1.0 200 OK Connection: close Content-Type: text/x-comma-separated-values Content-Length: 883 "SITE_TAG","MEMBER_ID","MEMBER_STATUS","PREVIOUS_MEMBER_STATUS","STATUS_CHANGE_DATE","MEMBER_USER_NAME","SIGNUP_DATE","EXPIRE_DATE","EMAIL_ADDRESS","RECURRING_STATUS","RECURRING_NEXT_DATE","RECURRING_PERIOD","RECURRING_PERIODS_LEFT","RECURRING_AMOUNT","NEXT_RECURRING_AMOUNT" "TEST1","100321355797","ACTIVE","","","Test","2004-08-04 17:52:04","2005-01-15 00:15:48","","BROKEN: TOO MANY FAILURES","4000-01-01 00:00:00","5","","0","0" "TEST1","100321273872","ACTIVE","","","Trans","2004-08-04 17:50:03","2005-01-15 10:08:31","test@test.com","BROKEN: TOO MANY FAILURES","4000-01-01 00:00:00","5","","0","0" "TEST1","100588461382","ACTIVE","","","User0001","2006-01-04 16:17:25","2006-01-10 16:17:37","","STOPPED: NO MORE PAY PERIODS","","1","0","0","0" "TEST1","100525811991","ACTIVE","","","test01","2005-04-12 15:31:51","2005-05-12 15:31:51","x@x.com","STOPPED: OK","","5","","0","0"
The following fields are those that will be returned following every successful request to the Transaction Reporting Interface.
| Field | Details |
|---|---|
| original_id | Indicates the ID of the original transaction which was the basis for this chargeback. This field is only returned when using the disputes_after / disputes_before parameters to query disputes. |
| original_date | The date of the original transaction which was the basis for this chargeback. This field is only returned when using the disputes_after / disputes_before parameters to query disputes. |
| return_date | The date when a return was reported for this NBCheck transaction. This field is only returned when using the returned_after / returned_before parameters to query NBCheck returns. |
| return_code | The NACHA standard reason code for this NBCheck return, such as "R01" indicating Non-Sufficient Funds. The AUTH_MSG field provides a text version of the error. This field is only returned when using the returned_after / returned_before parameters to query NBCheck returns. |
| trans_id | The unique 12-digit transaction ID identifying the given transaction. |
| trans_status_code | Single character status code.
"I" - Pending transaction, such as an unfunded NBCheck payment "R" - Refunded transaction "T" - Successful auth only transaction "0" - Failed transaction "F" - Settlement failure or returned NBCheck transaction |
| trans_status_msg | A human readable status message corresponding to the trans_status_code above, for example "SALE/OK" or "SALE/FAILED". Please note that these messages may change over time and are not intended to be machine readable. |
| site_tag | The site tag, if any, this transaction was submitted in association with. |
| origin | The origin of the given transaction. This will typically be one of the following:
"ND3.TRANS" - Direct Mode 3.x Transaction "ND2.TRANS" - Direct Mode 2.x Transactions "N2.PURCHASE" - 2.2 Native Payment Form Transaction "N2.SIGNUP" - 2.2 Native Payment Form Membership Signup Transaction "RECURRING" - Automated recurring billing transaction "BA.TRANS" - Transaction submitted as part of a batch upload |
| issue_date | The date (YYYY-MM-DD HH:MM:SS) the given transaction was issued. |
| member_id | The unique 12-digit member ID, if any, this transaction was submitted in association with. This ID can be used to directly tie transactions to the associated membership. |
| amount | The dollar amount of the given transaction. |
| currency | The 3 letter currency code of the processing currency. (e.g. "USD") |
| auth_msg | A human readable approval message, for example "APPROVED 123456", or "DECLINED 05". These messages are processor specific, may change, and are not intended to be machine readable. |
| card_type | The abbreviated card issuer for the transaction. For example, "VISA", "MC", "DISC", "AMEX", etc. |
| card_number | The partial card number of the transaction in question. This partial card number will have all but the trailing 4 digits blocked out. For NBCheck transactions this field will contain the partial routing:account number for the transaction. |
| card_expire | The expiration date (MMYY) for the card number. For NBCheck transactions this field will be empty. |
| description | The product description data associated with the given transaction. This data will be provided as it appears on the transaction details page for the transaction in the web system interface. |
| bill_name1 | The first name of the customer associated with this transaction. |
| bill_name2 | The last name of the customer associated with this transaction. |
| bill_street | The billing street address associated with this transaction. |
| bill_city | The billing city associated with this transaction. |
| bill_state | The billing state associated with this transaction. |
| bill_zip | The billing ZIP code associated with this transaction. |
| bill_country | The billing country associated with this transaction. |
| ship_name1 | The first name on the shipping address associated with this transaction. |
| ship_name2 | The last name on the shipping address associated with this transaction. |
| ship_street | The shipping street address associated with this transaction. |
| ship_city | The shipping city associated with this transaction. |
| ship_state | The shipping state associated with this transaction. |
| ship_zip | The shipping ZIP code associated with this transaction. |
| ship_country | The shipping country associated with this transaction. |
| customer_ip | The remote IP address associated with the given transaction. Note that this data will only be available if it (or the hostname) was provided to the system at the time the transaction was processed. |
| customer_host | The hostname associated with the given transaction. Note that this data will only be available if it (or the ip address) was provided to the system at the time the transaction was processed. |
| customer_email | The e-mail address of the customer as it was submitted at the time the transaction was processed. |
| misc_info | The misc info associated with the given transaction. This data will be provided as it appears on the transaction details page for the transaction in the web system interface. |
| user_data | The user data associated with the given transaction. This data will be provided as it appears on the transaction details page for the transaction in the web system interface. |
| dispute_type | Provided when downloading transactions with charged_back_after / charged_back_before. Values can be:
|
| dispute_post_date | Provided when downloading transactions with charged_back_after / charged_back_before. Date (YYYY-MM-DD HH:MM:SS) of dispute/chargeback posting to bank. This field can appear "back-dated" due to bank data import delays. |
| Provided when downloading transactions with charged_back_after / charged_back_before. Date (YYYY-MM-DD HH:MM:SS) of dispute/chargeback reporting in the system. The charged_back_after / charged_back_before query parameters are matched based on this date. | |
| dispute_msg | Provided when downloading transactions with charged_back_after / charged_back_before. An acquirer-specific code or message string, indicating the reason for the dispute. |
| master_id | For refunds or recurring billing, this is the trans_id of the original transaction. |
| processor | The processor routing prefix used to process transaction. This is useful primarily for load-balanced multi-processor accounts. |
| affiliate_tag | Merchant specified affiliate tag (if any) for transaction. |
| processor_rec_id | The processor record ID for transaction. Not all processors provide this. Some processors modify this value after successful settlement. |
| customer_phone | The customer's phone number (if specified) for transaction. |
The following is an example of a typical request and response exchange for the Transaction Reporting Interface:
Request:
POST /gw/reports/member1.4 HTTP/1.0
Host: secure.netbilling.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 104
account_id=200274083904&site_tag=CLOTHING&transactions_after=2006-03-22&authorization=OFFICE_1234
HTTP/1.0 200 OK Connection: close Content-Type: text/plain Content-Length: 1627 "TRANS_ID","TRANS_STATUS_MSG","TRANS_STATUS_CODE","SITE_TAG","ORIGIN","ISSUE_DATE","MEMBER_ID","AMOUNT","AUTH_MSG","CARD_TYPE","CARD_NUMBER","CARD_EXPIRE","DESCRIPTION","BILL_NAME1","BILL_NAME2","CUSTOMER_IP","CUSTOMER_HOST","CUSTOMER_EMAIL","MISC_INFO","USER_DATA" "200592674898","SALE/OPEN","1","CLOTHING","ND3.TRANS","2006-03-23 12:54:40","200592674899","19.95","TEST APPROVED","VISA","xxxxxxxxxxxx1111","0110","30 day subscription.","John","Smith","255.255.255.0","clothing.com","JohnSmith@anywhere.com","Special offer.","Customer number: 1237 Order number: 16" "200592920662","SALE/OPEN","1","CLOTHING","ND2.TRANS","2006-03-24 10:32:50","200592937042","14.95","TEST APPROVED","VISA","xxxxxxxxxxxx1111","0408","30 day subscription.","Dave","Rowan","255.255.255.0","clothing.com","DaveRowan@somewhere.com","Special offer.","" "200593707010","SALE/OPEN","1","CLOTHING","V-TERM","2006-03-24 14:33:36","","9.95","TEST APPROVED","VISA","xxxxxxxxxxxx1111","0407","30 day subscription.","Jake","Williams","","","JakeWilliams@billing.net","Special offer.","" "200593707015","SALE/OPEN","1","CLOTHING","ND2.TRANS","2006-03-24 14:39:08","200593723395","4.95","TEST APPROVED","VISA","xxxxxxxxxxxx1111","0708","10 day subscription.","Kelly","Dale","124.54.163.0","school.somewhere.edu","KellyDale@school.edu","Special sale offer.","" "200593641490","SALE/OPEN","1","CLOTHING","ND3.TRANS","2006-03-24 14:39:20","200593641491","7.75","TEST APPROVED","VISA","xxxxxxxxxxxx1111","0211","T-shirt.","Clara","Williams","147.22.255.0","access.internet.com","ClaraWilliams@access.net","2 day sale only.","Customer number: 1947 Order number: 12"
Exceptions are returned when an invalid request is sent to the system or another abnormal condition occurs. Exceptions are reported
as HTTP errors and correspond to how exceptions are used in programming languages. HTTP codes other than 200 indicate an exception.
The HTTP message will contain a brief description of the error.
Normally clients should be designed to treat all non-200 HTTP codes as errors and return the HTTP message to the user. It is not recommended to program for individual handling of all possible exceptions. Special handling for certain errors may be desirable and can be done by determining the specific code returned for that error and using that to check for similar errors in the future. All non-standard HTTP response codes will fall in the range of 500-598 and will indicate that some type of improper input was submitted to the system. For example:
HTTP/1.0 506 No valid authorization for requested site_tag(s) Connection: close Content-Type: text/x-comma-separated-values Content-Length: 0Note: If you're testing the interface with a web-browser rather than from a programming language, you may not be able to see the error codes because many browsers display a generic error page, or a blank page, rather than the specific error message returned from the server.