This 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.
The 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 into 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.
Data Link accepts input parameters sent to the following script:
https://datalink.ccbill.com/data/main.cgi
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:
https://datalink.ccbill.com/data/main.cgi?var1=value&var2=value
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.
transactionTypes
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. |
The 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:
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 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.
Each 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 |
Merchants 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.
To 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:
https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=EXPIRE&clientAccnum=900100&clientSubacc=0000&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&merchantSubacc=0000&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12&testMode=1
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&username=user1234&password=passwd12&testMode=1
The 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.
Data 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:
| Error Code | Description |
|---|---|
| 01 | Too many failed logins |
| 02 | Failed Login |
| 03 | Inactive username |
| 04 | Check IP failed (most likely out of range) |
Contact Merchant Support if you require assistance troubleshooting any of these errors.