NETbilling has the most powerful Direct Mode payment interfaces available in the gateway industry. These interfaces allow merchants to completely automate payment processing. The Data Retrieval Interface (formerly known as "Scriptable Reporting Interface" or SRI, prior to version 1.5) 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 Data Retrieval 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 Data
Retrieval Interface and is intended for a technical audience. Knowledge of HTTP standards is
assumed.
To make client implementation as simple as possible, the Data Retrieval 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 Data Retrieval Interface:
| Host | Description |
|---|---|
| https://secure.netbilling.com/gw/reports/member1.5 | Member Reporting Interface |
| https://secure.netbilling.com/gw/reports/transaction1.5 | 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 "Data Retrieval 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 Data Retrieval Interface
protocol as well as which of these are required for proper operation of each of the separate interfaces.
The following standard HTTP headers are expected in the request.
| Header | Status | Comments |
|---|---|---|
| Content-Length | Required | The length of the POST request body in bytes. |
| Content-Type | Required | The value must be "application/x-www-form-urlencoded" |
| Host | Optional | The name of the server you are connecting to: "secure.netbilling.com" |
| User-Agent | Required | A descriptive name of your client software and the most recent date it was updated. is is important because it allows us to identify and notify clients using old software when new features are added to the protocol. Example: "MyDRIClient/Version:2010.Feb.20" |
The following input parameters are necessary for proper operation of both the Member and Transaction Data Retrieval 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.5). At least one "_after" parameter must always be specified. Ensure the date range is limited to period of interest only, and avoid repetitive requests returning the same data. Excessive usage triggers automatic IP lock-out for up to 24 hours. These limits should never be a problem for a properly coded client implementation.
Date formats with or without 24-hour times can be used. "2013-12-31" is identical to "2013-12-31 00:00:00". A range includes records on or after the start-time, until immediately before the end-time. This ensures that records at the boundaries are returned exactly once, and the client can simply reuse the most recent end-time as the start-time for the next request.
For example, a contiguous range can be fetched by combining multiple requests and intervals:
| Req. No. | Transactions After | Transactions Before |
|---|---|---|
| 1st | 2012-12-29 | 2012-12-30 |
| 2nd | 2012-12-30 | 2012-12-31 |
| 3rd | 2012-12-31 | 2013-01-01 |
| 4th | 2013-01-01 | 2013-01-01 08:00:00 |
| 5th | 2013-01-01 08:00:00 | 2013-01-01 16:00:00 |
| 6th | 2013-01-01 16:00:00 | 2013-01-02 00:00:00 |
| 7th | 2013-01-02 | 2013-01-05 |
The following date-range parameters are supported:
| 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. |
Table 2.3.1 *One of these parameters must be provided. |
||
The following is an example of a typical HTTP POST request to the Member Reporting Interface for a single site tag:
The following is an example of a typical HTTP POST request to the Member Reporting Interface for multiple site tags with multiple access keywords:
The following input parameters are for use with the Transaction Reporting Interface (transaction1.5).
| Parameter | Condition | Details |
|---|---|---|
| transactions_after | Required1 | Transactions issued on or after the date specified by this field will be returned. |
| transactions_before | Optional | If Used, transactios issued before the date specified by this field will 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 | |
| captured_after | Required1 | Previously authorizied transactions which were captured on or after the date specified will be returned. When specified, only transactions subject to delayed capture will be returned. |
Table 2.4.1 1At least one of these fields is required.
| ||
The following is an example of a typical HTTP POST request to the Transaction Reporting Interface for a single site tag:
The following is an example of a typical HTTP POST request to the Transaction Reporting Interface for multiple site tags with multiple access keywords:
This section will outline and explain all response fields provided by the Data Retrieval 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. New columns may be added in the future and the column ordering may change. The client MUST parse the header line to determine the column numbers when processing a response.
Standard HTTP headers are returned in the response:
| Header | Present | Comments |
|---|---|---|
| Content-Type | Always | The value is normally "text/x-comma-separated-values", but "text/plain" is used for the body of error messages. |
| Content-Length | Not Always | For some reports the Content-Length is not known until after the response has been streamed to the client. You should continue reading until an End-Of-File is received on the socket. |
| Retry-After | In case of HTTP 503 Service Unavailable | This header is sent for HTTP 503 response codes. It indicates the number of seconds your client should wait before resubmitting
the request. We strongly recommend that all clients implement this to ensure that the response is received as soon as it's available.
We process certain requests asynchronously, the criteria for which is subject to change. If you fail to implement Retry-After handling, your client may stop working in the future. |
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:
|
| 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. Status messages are subject to change. Current messages are:
|
| 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:
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.
|
| 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:
|
| issue_date | The date (YYYY-MM-DD HH:MM:SS) the given transaction was issued. |
| capture_date | The date (YYYY-MM-DD HH:MM:SS) a previously authorized transaction was captured. This field is blank for transactions which were not subject to delayed capture. |
| 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. |
| customer_phone | The customer's phone number (if specified) for transaction. |
| 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. |
| dispute_report_date | 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. |
| settle_id | The gateway's settlement ID for the transaction. Will be blank or 0 for unsettled transactions. Can be used as a tool for grouping transactions together by batch, since transactions in settled in a batch will all have the same settle_id. |
| card_flags | Will be P if the card is a prepaid card, blank otherwise. |
The following is an example of a typical request and response exchange for the Transaction Reporting Interface:
Request:
Exceptions result from invalid requests, excessive usage or other abnormal conditions. Exceptions are returned
as HTTP header error codes, and would typically trigger an exception in the client programming language.
HTTP codes other than 200 indicate an exception. The HTTP message will contain a brief description.
Clients should be designed to treat all non-200 HTTP codes as exceptions and display or log the code anandd message. It's not recommended to implement individual handlers for all possible exception codes. A catch-all handler is usually sufficient. Sometimes special handling of an exception is useful, such as for the 503 code described below. Test whether the HTTP error code matches a particular code seen previously. Note that new exception codes are added, and text messages are subject to change.
One important error code, 503 Service Unavailable, does require special handling. When a 503 code is received, the client will also receive a HTTP Retry-After header. This header indicates the number of seconds the client must wait before resubmitting the request. This is part of the HTTP/1.1 protocol standard described in RFC2616, but is not automatically supported by all client libraries.
Example 1: