Data Link Extract System User Guide
IntroductionThis document is provided as a technical resource for CCBill merchants. It is written for programmers, technicians, and other individuals with advanced programming skills.
The information in this document pertains to constructing an Application Program Interface (API) with the CCBill Data Link Extract System.
OverviewThe Data Link Extract System (Data Link) allows CCBill merchants to access raw transaction data by submitting specified parameters to the Data Link CGI script. The data is then returned in the form of a comma-separated value (CSV) dataset that can be read by the script requesting the information and displayed through a custom reporting engine. Requests sent directly through a Web browser’s address bar will produce an on-screen “data dump” within the browser window. An error will be returned if the request is invalid or rejected.
The values passed in to the Data Link CGI script act as search parameters to “filter” the information in the returned dataset. You may search by date range, transaction type, merchant account number, and sub-account number. You will be required to include a username and password in the request string, and you may optionally include the Test Mode parameter to use for testing purposes.
To prevent abuse of the system, Data Link requests can only be made once every 60 minutes.
Input ParametersData Link accepts input parameters sent to the following script:
Each of the following search terms are variables that must be passed into the script. They can be passed in any order. The first variable passed in must be preceded by the question mark (?) character, and each subsequent variable should be preceded by the ampersand (&) character. For example:
The following variables must be passed into the string:
startTime and endTime
startTime and endTime are separate variables that represent the date and time during which the transactions took place. The values must be passed in YYYYMMDDHHIISS format with hours expressed in 24-hour military format. Specified date ranges cannot exceed 24 hours; dates entered outside this range will produce an error and terminate the script.
Several transaction types can be requested: NEW, REBILL, REFUND, VOID, EXPIRE, CHARGEBACK, CANCELLATION, and CDS (Merchant-driven Settlement). Separate multiple types with a comma; for example, to show new subscriptions and rebills, enter transactionTypes=NEW,REBILL. The following list shows all possible transaction types that can be requested:
|NEW||New subscriptions; this includes recurring and single billing.|
|REBILL||Subscriptions that have rebilled successfully.|
|REFUND||Refunded subscriptions or rebills.*|
|VOID||Subscriptions or Rebills that have been declared void.|
|EXPIRE||Expired subscriptions have either reached the end of their subscription period or been cancelled and reached their renewal date.|
|CHARGEBACK||Subscriptions or rebills that have been charged back.|
|CANCELLATION||Subscriptions that have been cancelled. Note that the use of this feature must be approved by CCBill Management.|
|CDS||Merchant-driven Settlement (CDS) transactions have been pre-authorized but funds will not be collected until the consumer logs in to the Members area for the first time.|
|AFFILIATE||Shows the Affiliate share of referred transactions completed during the specified timeframe.|
|ACTIVEMEMBERS||Lists Active Members at the time of the Datalink request for an account or sub-account number. If no sub-account number is defined a list of all active members for all sub-accounts shall be returned. Note: the startTime and endTime parameters are not required for this transactionType.
Unrecognized values passed in to the transactionTypes variable will produce an error and cause the script to terminate.
|clientAccnum||This variable specifies the six-digit merchant account number of the account for which data is being requested.|
|clientSubacc||This parameter is optional and defines the sub-account for which data is being requested. If this parameter is not included, data from all sub-accounts underneath the merchant account will be returned.|
|username||The username parameter is provided during the initial setup of the account and used only to authenticate Data Link requests. If the sub-account number is specified then the username must correspond to that sub-account.|
|password||The password parameter is provided during the initial setup of the account and used only to authenticate Data Link requests. If the sub-account number is specified then the password must correspond to that sub-account.|
|testMode||This parameter is optional and is used only for testing purposes to ensure your system is interfacing correctly with Data Link. Pass in a value of “1” for this parameter to enable Test Mode; otherwise do not include it.|
ResponseThe requested data will be returned in comma-separated value (CSV) format. Fields and their values will depend on the information requested. All fields are returned inside quotation marks and any quotes within the values are escaped.
Data Link requests can be customized using the CCBill Admin Portal system:
- Log in to the Admin Portal and navigate to the Account Info mega menu.
- Click the Data Link Services Suite link.
- Click the View Data Formats button to see a list of potential transaction types.
- Click the Customize link next to the transaction type to select which fields you would like to receive for that transaction type. You will be taken to the Field Select screen.
- The Available Fields box shows a list of available fields that are available but not currently being returned. The Selected Fields box shows all the fields that are currently being returned.
- To add a field to the data set for the selected transaction type, select it from the Available Fields box and click the Add button (you may select more than one field by holding the Control key while selecting individual fields).
- Field values are returned in the order they appear in the Selected Fields box. To change the order, select a value in the list and click the up and down arrows to right of the box to move the selected item up or down in the list.
To remove a field from the dataset, select it in the Selected Fields box and click the Remove button (you may select more than one field by holding the Control key while selecting individual fields).
When finished, click the Submit Changes button. To cancel your changes and return to the Data Formats list, click the Cancel button.
Field DefinitionsField values are returned in the form of a data record set. The following fields can be read from this dataset using data retrieval functions (data types are in parentheses):
|Transaction Type (string)||The category under which the transaction falls.|
|Merchant account number (integer)||Six-digit CCBill merchant account number.|
|Merchant Sub-account (integer)||Four-digit sub-account number.|
|Subscription ID (integer)||Unique identification number for the subscription.|
|Transaction Timestamp (string)||Exact time the transaction took place. Value is returned as a 14-digit integer in YYYYMMDDHHIISS format. For types REBILL and EXPIRE, the value will return as a string in YYYY-MM-DD format.|
|First Name (string)||Consumer’s first name.|
|Last Name (string)||Consumer’s last name.|
|Username (string)||Consumer’s username.|
|Password (string)||Consumer’s password.|
|Address (string)||Consumer’s billing address.|
|City (string)||Consumer’s city.|
|State (string)||Consumer’s state.|
|Postal Code (string)||Consumer’s zip/postal code.|
|Country (string)||Country in which the consumer resides.|
|Email Address (string)||Consumer’s email address.|
|Partner ID (string)||Unique identifier that denotes the partner who referred the sale. The value will have an asterisk (*) character appended if the partner is not a CCBill affiliate.|
|Subscription Status (string)||Returns ‘Y’ or ‘N’ to show whether the subscription is currently active.|
|Accounting Amount (float)||This value represents the amount in U.S. Dollars (USD) that was paid, voided, refunded, or charged back. For NEW and CDS transactions, this value represents the initial (first) billing price.|
|Initial Period (integer)||Length of the first billing period. The initial period denotes the trial period if the subscription began with a trial.|
|Recurring Accounting Amount (float)||The amount the merchant receives in USD for each recurring transaction. This amount may vary due to applicable currency conversion rates.|
|Recurring Period (integer)||Time in between rebills. Will return 0 (zero) for single bills.|
|Recurring Status (integer)||The remaining number of rebills left for the subscription. Single bills return 0; indefinite recurring subscriptions return 99.|
|Card Type (string)||The type of credit card used (Visa, MasterCard, JCB, Discover, etc.) Value will return blank if not a credit card transaction.|
|Billed Amount (float)||Amount charged in the consumer’s currency.|
|Billed Currency (integer)||3-digit currency code to denote the currency type in which the consumer paid.|
|Base Initial Price (float)||Initial price set by merchant. This should be used in conjunction with Base Currency; for example, if the initial price is 30 EUR, the Base Initial Price is 30. If the initial price is 20 USD, the Base Initial Price is 20.|
|Base Currency (string)||Currency type on which the payment option was based.|
|Base Recurring Price (float)||Recurring price on which the payment option was based.|
|Expire Date (string)||Expiration date for the subscription, returned in YYYY-MM-DD format.|
|Cancel Date (string)||Date the subscription was cancelled, returned in YYYY-MM-DD format.|
|Rebill Transaction ID (integer)||Unique identification number for the rebill transaction.|
|Batched Transaction (string)||Batched transactions are pre-approved because of technical issues during signup; this can happen in the case of a network outage or delay in bank authorization. The field will return ‘Y’ for a failed batch transaction or ‘N’ for a successful batch transaction.|
|Billing Terms Type (string)|| This value will return one of the following for NEW transaction types:
1. TIERED. This value will return for Tiered Subscription System (TSS) transactions.
2. ONE-TIME. This value will return for standard non-TSS single-billing transactions.
3. RECURRING. This value will return for standard non-TSS recurring transactions.
For REBILL transaction types, the Billing Terms Type will return one of the following:
1. TIERED. This value will return for TSS transactions.
2. REBILL. This value will return for standard non-TSS rebill transactions.
|Billing Contract ID (integer)||For Tiered Subscription System transactions, this field will contain the Contract ID number. For non-TSS transactions, this field will return null.|
|Amount (float)||The amount paid to the Affiliate for the referenced transaction.|
|Affiliate System (string)||The Affiliate System used for the transaction; WMS or Legacy.|
|Reservation ID||The Reservation ID is a variable that is matched to the Username with User Management for logging purposes.|
Once the customization is complete, you can Edit or Reset the desired values by clicking the appropriate link next to the transaction type in the Data Formats list. Resetting will set the returned fields to the default set as shown in the Transaction Type Defaults section below.
Transaction Type DefaultsEach transaction type returns a specific set of fields by default which can be modified to only deliver the information desired. The following list shows the default fields that are returned for each transaction type; these fields can be removed and re-added at any time:
|NEW||Merchant Sub Account, Subscription ID, Transaction Timestamp, First Name, Last Name, Username, Password, Address, City, State, Postal Code, Country, Email Address, Partner ID, Subscription Status, Accounting Amount, Initial Period, Recurring Accounting Amount, Recurring Period, Recurring Status, Card Type, Billing Terms Type, Billing Contract Id|
|REBILL||Merchant Sub Account, Subscription ID, Transaction Timestamp, Rebill Transaction ID, Accounting Amount, Billing Terms Type, Billing Contract Id|
|REFUND||Merchant Sub Account, Subscription ID, Transaction Timestamp, Accounting Amount|
|CHARGEBACK||Merchant Sub Account, Subscription ID, Transaction Timestamp, Accounting Amount|
|EXPIRE||Merchant Sub Account, Subscription ID, Expire Date, Cancel Date, Batched Transaction|
|CANCELLATION||Merchant Sub Account, Subscription ID, Expire Date, Cancel Date, Batched Transaction|
|VOID||Merchant Sub Account, Subscription ID, Transaction Timestamp, Accounting Amount|
|CDS||Merchant Sub Account, Subscription ID, Transaction Timestamp, First Name, Last Name, Username, Password, Address, City, State, Postal Code, Country, Email Address, Partner ID, Subscription Status, Accounting Amount, Initial Period, Recurring Accounting Amount, Recurring Period, Recurring Status, Card Type, Cancel Date|
|AFFILIATE||Merchant Sub Account, Transaction Time, Subscription ID, Amount|
|ACTIVEMEMBERS||Merchant Sub Account, Subscription ID, Transaction Timestamp, First Name, Last Name, Username, Password, Address, City, State, Postal Code, Country, Email Address, Partner ID, Subscription Status, Accounting Amount, Initial Period, Recurring Accounting Amount, Recurring Period, Recurring Status, Next Rebill Date, Card Type, Billing Terms Type, Billing Contract ID, Expire Date, Affiliate System|
AuthenticationMerchants must call CCBill Merchant Support to enable Data Link connections on an account. Merchant Support will need the following information: merchant account number, sub-account number (if only desired for one sub-account), a new and unique username, a new and unique password, and the IP address of the requesting system. A range of IP addresses can be used, but all must be owned by the merchant or the request may be rejected.
If the credentials of the Data Link request do not match, authentication will fail and the script will terminate.
Requesting Transaction DataTo request transaction data from Data Link, send a standard HTTPS request to https://datalink.ccbill.com/data/main.cgi with the appropriate variable values appended. The following are examples of valid Data Link requests:
NEW transaction request without merchant sub-account number:
Multiple transaction requests without merchant sub-account number:
NEW transaction request with optional merchant subaccount number:
Multiple transactions request with optional merchant subaccount number:
NEW Test Mode* transaction request without merchant subaccount number:
Multiple Test Mode* transaction requests without merchant subaccount number:
*Test ModeThe Test Mode feature allows you to test the Data Link system and ensure that your software is interfacing correctly with our system. The data that is returned to you is for testing purposes only and is returned in the same format as during normal operation. When in Test mode, there is no time restriction and therefore the waiting period is eliminated.
TroubleshootingData Link generates an error when the script is unable to process your request. Errors are preceded by an “Error:” string and echoed as output when displayed in a browser. The following is a list of some errors that may occur:
- Invalid field format or absent value.
- Selected period is greater than 24 hours.
- Start date is greater than end date.
- Authentication failed due to incorrect username and/or password.
- IP address locked due to several failed login attempts.
- System is down for maintenance.
- A request has been made within the last 60 minutes.