This document is provided as a technical resource to CCBill merchants.
The information contained in this document concerns establishing and using the merchant-side consumer service Application Program Interface (API). The Subscription Management script replaces the Custom Cancel script and provides additional new features. The information contained in this document outlines the Subscription Management functionality and its interaction with the CCBill User Management System. Proper setup of the Data Link Extract System is required before the CCBill API can be utilized.
The subscriptionManagement.cgi script replaces the customCancel.cgi script in the Data Link Extract System. The CCBill API has additional features that were not included in the customCancel.cgi.
Before the subscriptionManagement.cgi script can be used your system must be set up to access the CCBill Data Link Extract System.
The CCBill Data Link Extract System allows CCBill merchants to access transaction data from the CCBill database with a CGI script. Consult the Data Link Extract User Guide for further information about Data Link Extract.
This parameter specifies the main CCBill merchant account number of the merchant that is requesting the data. The value must be a six digit number.
This is the username that was setup for authentication on the Data Link Extract system.
This is the password that was setup for authentication on the Data Link Extract system.
This is the function to be performed within the CCBill API. See Supported Actions for a complete list of available options.
The table lists the parameters that are always required regardless if the action is to be performed on the main account or on a subaccount:
| clientAccnum | username | password | action |
| Main Account | X | X | X |
| Sub Account | X | X | X |
Main Account Number - All CCBill merchants receive an account number for tracking purposes. The standard format is 9xxxxx-xxxx, where 9xxxxx is the main account. The main account is a 6-digit number. For example: "900000".
Sub Account Number - After a merchant signs up for website billing, they may open one or more subaccounts. The subaccount is a 4-digit number. The standard format is: xxxx. For example: "0002". The subaccount is part of the main account.
This is the specific subaccount number the subscription is related to; it must be four digits long. If this parameter is provided, you will be authenticated on a specific subaccount and not on the main account. Any requested action must pertain to this subaccount,otherwise the operation will fail.
Use this parameter if you wish to be authenticated on the main account but not on a specific subaccount. This parameter specifies a subaccount on which a requested operation will be performed.
Note: If clientSubacc is passed in along with usingSubacc, they must have the same value for a successful authentication. Different values would cause you to authenticate on a specific subaccount and operate on another.
If this parameter is passed in, you will receive the information in XML format; otherwise the information is returned in CSV (comma separated values) format.
Reports the status of a customer subscription.
| viewSubscriptionStatus | clientSubacc | usingSubacc | subscriptionId | returnXML |
| Main Account | O | X | ||
| Main Account w/XML | O | X | X | |
| Sub Account | X | X | ||
| Sub Account w/XML | X | X | X |
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
"cancelDate","signupDate","chargebacksIssued","timesRebilled","expirationDate","recurringSubscription","subscriptionStatus","refundsIssued","voidsIssued""20050228","20050228170442","0","0","20050228","1","0","1","0"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123& returnXML=1&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results> <cancelDate>20050228</cancelDate> <chargebacksIssued>0</chargebacksIssued> <expirationDate>20050228</expirationDate> <recurringSubscription>1</recurringSubscription> <refundsIssued>1</refundsIssued> <signupDate>20050228170442</signupDate> <subscriptionStatus>0</subscriptionStatus> <timesRebilled>0</timesRebilled> <voidsIssued>0</voidsIssued> </results>
Reports the discount information of a consumer subscription.
| viewDiscountInfo | clientSubacc | usingSubacc | subscriptionId | returnXML |
| Main Account | O | X | X | |
| Main Account w/XML | O | X | X | |
| Sub Account | X | X | ||
| Sub Account w/XML | X | X | X |
Note: Discounts can only be setup for recurring subscriptions. Also, to be eligible for a discount, the subscription’s recurring price must be at least $5.00.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
"startPeriod","amount","discounts","discountInterval","type","startDate""1","1.00","1","1","CANCEL","20050228173436"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password =test123&returnXML=1&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?>
<results>
<discountInfo>
<amount>1.00</amount>
<discountInterval>1</discountInterval>
<discounts>1</discounts>
<startDate>20050228173436</startDate>
<startPeriod>1</startPeriod>
<type>CANCEL</type>
</discountInfo>
</results>
Applies a previously set up cancel discount to a given subscription.
| applyDiscount | clientSubacc | usingSubacc | subscriptionId | returnXML |
| Main Account | O | X | ||
| Main Account w/XML | O | X | X | |
| Sub Account | X | O | X | |
| Sub Account w/XML | X | O | X | X |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=applyDiscount&clientAccnum=923590
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=applyDiscount&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Voids a consumer’s transaction, if still eligible. The most current consumer transaction can be annulled for a defined period before the transaction is settled.
The consumer will not be charged.
| voidTransaction | clientSubacc | usingSubacc | subscriptionId | returnXML |
| Main Account | O | X | ||
| Main Account w/XML | O | X | X | |
| Sub Account | X | X | ||
| Sub Account w/XML | X | X | X |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=voidTransaction&clientAccnum=923590
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=voidTransaction&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Merchants can perform a full or partial refund. Passing in a specific amount will initiate a refund for that designated amount; please note that refunds cannot exceed the amount of the initial transaction. Omitting the amount results in a full refund equivalent to the initial transaction amount.
refundTransaction API will also cancel and expire the subscription, either for a partial or a full refund request. In cases where merchants do not want the consumer subscriptions to be canceled after a refund, they can refund the transactions from Admin portal instead of using the API.
| modifyUserCredentials | clientSubacc | usingSubacc | subscriptionId | Amount |
| Main Account | O | X | O | |
| Main Account w/XML | O | X | O | |
| Sub Account | X | X | O | |
| Sub Account w/XML | X | X | O |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Attempts to void the transaction. If the transaction can no longer be annulled because the defined period has passed, the transaction will be refunded. Partial refunds can be given by passing in the amount parameter. If the amount is passed in but the transaction can be voided, the transaction will be voided. To issue full or partial refunds without attempting to void the transaction, see the refundTransaction section of this document.
| voidOrRefundTransaction | clientSubacc | usingSubacc | subscriptionId | returnXML | amount |
| Main Account | O | X | O | ||
| Main Account w/XML | O | X | X | O | |
| Sub Account | X | X | O | ||
| Sub Account w/XML | X | X | X | O |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Re-adds or changes the username and/or password for an active subscription.
| modifyUserCredentials | clientSubacc | usingSubacc | subscriptionId | custUsername | custPassword | returnXML |
| Main Account | O | X | O | O | ||
| Main Account w/XML | O | X | O | O | X | |
| Sub Account | X | X | O | O | ||
| Sub Account w/XML | X | X | O | O | X |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590&returnXML=1
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Manually adds a user to the account. The user will have access to the site up until the date specified by the 'endDate' parameter. This option bypasses the subscription model.
| manualAdd | clientSubacc | usingSubacc | custUsername | custPassword | endDate | generateRandom | returnXML |
| Main Account | X | X | X | X | |||
| Main Account w/XML | X | X | X | X | X | ||
| Sub Account | X | X | X | X | |||
| Sub Account w/XML | X | X | X | X | X | ||
| Main Account w/Random | X | X | X | ||||
| Main Account w/XML and Random | X | X | X | X | |||
| Sub Account w/Random | X | X | X | ||||
| Sub Account w/XML and Random | X | X | X | X |
When this option is used, the username and password will be generated randomly and therefore, the parameters username and password are not required.
When these parameters are passed in, the username and password will be set to the respective values and therefore not be generated randomly.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590
Return
“endDate”,” username”,” password” 20050330,manualAdd1,test123
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&returnXML=1&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results> <endDate>20050330</endDate> <username> manualAdd1</username> <password> test123</password> </results>
Removes a consumer’s ability to access your site.
| manualRemove | clientSubacc | usingSubacc | custUsername | returnXML |
| Main Account | X | X | ||
| Main Account w/XML | X | X | X | |
| Sub Account | X | X | ||
| Sub Account w/XML | X | X | X |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
Extends the length of an existing consumer subscription. The ‘extendLength’ parameter is used to extend the subscription by a number of days.
| manualRemove | clientSubacc | usingSubacc | returnXML | extendLength |
| Main Account | X | X | ||
| Main Account w/XML | X | X | X | |
| Sub Account | X | X | ||
| Sub Account w/XML | X | X | X |
A success or failure code will be returned.
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30
Return
"results" "1"
Request string
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30&returnXML=1
Return
<?xml version='1.0' standalone='yes'?> <results>1</results>
| Success Codes | |
|---|---|
| 1 | The requested action was a success. |
| Code | Description |
|---|---|
| 0 | The requested action failed. |
| -1 | The arguments provided to authenticate the merchant were invalid or missing. |
| -2 | The subscription id provided was invalid or the subscription type is not supported by the requested action. |
| -3 | No record was found for the given subscription. |
| -4 | The given subscription was not for the account the merchant was authenticated on. |
| -5 | The arguments provided for the requested action were invalid or missing. |
| -6 | The requested action was invalid |
| -7 | There was an internal error or a database error and the requested action could not complete. |
| -8 | The IP Address the merchant was attempting to authenticate on was not in the valid range. |
| -9 | The merchant’s account has been deactivated for use on the Datalink system or the merchant is not permitted to perform the requested action |
| -10 | The merchant has not been set up to use the Datalink system. |
| -11 | Subscription is not eligible for a discount, recurring price less than $5.00. |
| -12 | The merchant has unsuccessfully logged into the system 3 or more times in the last hour. The merchant should wait an hour before attempting to login again and is advised to review the login information. |
| -15 | Merchant over refund threshold |
| -16 | Merchant over void threshold |
| -23 | Transaction limit reached |
| -24 | Purchase limit reached |
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=cancelSubscription&subscriptionId=1000000000&returnXML=1
The merchant is attempting to authenticate on the main account 900100. The clientSubacc parameter is not passed in and therefore will the authentication take place on the main account. The request is to see the subscription status of Subscription ID 1000000000. Since the clientSubacc parameter was not passed in, the Subscription ID can be from any subaccount under the 900100 account. Had it been passed in, the Subscription ID would have to be for the specified subaccount. The merchant is requesting the information to be returned in XML format.
<?xml version='1.0' standalone='yes'?> <results> <cancelDate>20050223</cancelDate> <chargebacksIssued>0</chargebacksIssued> <expirationDate>20050324</expirationDate> <recurringSubscription>1</recurringSubscription> <refundsIssued>0</refundsIssued> <signupDate>20050222162551</signupDate> <subscriptionStatus>1</subscriptionStatus> <timesRebilled>0</timesRebilled> <voidsIssued>0</voidsIssued> </results>
The subscription’s initial signup date and time was 02/22/2005 at 04:25:51 PM. It is a recurring subscription. The expiration date for the subscription is 03/24/2005. The subscription is in an active status; however, it has been cancelled by the customer on 02/23/2005. There were no rebills, voids, refunds or chargebacks for the subscription.
https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900000&username=myusername&password=mypassword&action=discountSubscription&discountAmount=2.00&subscriptionId=0012946984374168
The merchant is attempting to authenticate on the 0002 subaccount that is under the account 900100. The request is to view the discount information for Subscription ID 1000000002. Because the merchant is authenticating on the 0002 subaccount, the subscription must be for that subaccount. A returnXML was not passed in and therefore the information will be returned in CSV format.
"startPeriod","amount","discounts","discountInterval","type","startDate" "3","5.00","2","1","LOYALTY","20050222162551"
The information reports that there is a discount set up for the subscription. The type of discount that was setup for the subscription type is a loyalty discount. The discount will start after 3 rebills. The discount is for $5.00 (the recurring price will be $5.00 less). The maximum of 2 discounts can be applied to the subscription. The interval between applied discounts is 1 rebill; this is the number or rebills that must occur before applying successive discounts. The initial subscription signup occurred on 02/22/2005.
CCBill API: Cancel Subscription
CCBill API: Advanced Dynamic Upgrades
CCBill API: One Click
CCBill API: Charge by Previous Transaction ID