CCBill API Guide

Introduction

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.

CCBill API

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.

Required Parameters for Authentication

clientAccnum

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.

username

This is the username that was setup for authentication on the Data Link Extract system.

password

This is the password that was setup for authentication on the Data Link Extract system.

action

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:

clientAccnumusernamepasswordaction
Main Account XXX
Sub Account XXX

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.

Optional Parameters

clientSubacc

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.

usingSubacc

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.

returnXML

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.

Supported Actions and Required Parameters

viewSubscriptionStatus

Reports the status of a customer subscription.

Required (X) and Optional (O) Parameters

viewSubscriptionStatusclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  OX 
Main Account w/XML  OXX
Sub Account X X 
Sub Account w/XML X XX

Information Returned

  • Whether or not the subscription is active.
  • The cancellation date of a cancelled subscription.
  • Is the subscription recurring or a single billing subscription?
  • The next billing date for recurring subscriptions or the expiration date for single billing subscriptions.
  • If the subscription has been voided, refunded, or charged back and the number of each occurrence.
  • The status of the subscription.

Status Codes:

  • 0 - The subscription is inactive.
  • 1 - The subscription is active but the customer has cancelled the subscription (pertains to recurring subscriptions).
  • 2 - The subscription is active and the customer has NOT cancelled their subscription or the subscription is a nonrecurring subscription.
  • On failure, an error code will be returned.

CSV Version Example

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"

XML VERSION EXAMPLE

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>

viewDiscountInfo

Reports the discount information of a consumer subscription.

Required (X) and Optional (O) Parameters

viewDiscountInfoclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X X
Main Account w/XML  O X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

  • Is the subscription eligible for a discount?

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.

  • Is a discount currently setup for the subscription?
  • What are the properties of the discount?
  • On failure, an error code will be returned.

CSV Version Example

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"

XML VERSION EXAMPLE

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>

applyDiscount

Applies a previously set up cancel discount to a given subscription.

Required (X) and Optional (O) Parameters

applyDiscountclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X 
Main Account w/XML  O X X
Sub Account X O X 
Sub Account w/XML X O X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

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"

XML VERSION EXAMPLE

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>

voidTransaction

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.

Required (X) and Optional (O) Parameters

voidTransactionclientSubaccusingSubaccsubscriptionIdreturnXML
Main Account  O X 
Main Account w/XML  O X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

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"

XML VERSION EXAMPLE

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>

refundTransaction

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.

Required (X) and Optional (O) Parameters

modifyUserCredentialsclientSubaccusingSubaccsubscriptionIdAmount
Main Account  O X O
Main Account w/XML  O X O
Sub Account X  X O
Sub Account w/XML X  X O

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

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"

XML VERSION EXAMPLE

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>

voidOrRefundTransaction

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.

Required (X) and Optional (O) Parameters

voidOrRefundTransactionclientSubaccusingSubaccsubscriptionIdreturnXMLamount
Main Account  O X  O
Main Account w/XML  O X X O
Sub Account  X  O
Sub Account w/XML  X X O

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

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>

modifyUserCredentials

Re-adds or changes the username and/or password for an active subscription.

Required (X) and Optional (O) Parameters

modifyUserCredentialsclientSubaccusingSubaccsubscriptionIdcustUsernamecustPasswordreturnXML
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

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

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"

XML VERSION EXAMPLE

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>

manualAdd

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.

Required (X) and Optional (O) Parameters

manualAddclientSubaccusingSubacccustUsernamecustPasswordendDategenerateRandomreturnXML
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
Sub Account w/Random X    X X 
Sub Account w/XML and Random X    X X X

Optional Parameters

generateRandom

When this option is used, the username and password will be generated randomly and therefore, the parameters username and password are not required.

custUsername/custPassword

When these parameters are passed in, the username and password will be set to the respective values and therefore not be generated randomly.

Information Returned

  • The username that was added.
  • The password that was added.
  • The endDate is the date when the consumer’s access will be removed.
  • On failure, an error code will be returned.

CSV VERSION EXAMPLE

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

XML VERSION EXAMPLE

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>

manualRemove

Removes a consumer’s ability to access your site.

Required (X) and Optional (O) Parameters

manualRemoveclientSubaccusingSubacccustUsernamereturnXML
Main Account  X X 
Main Account w/XML  X X X
Sub Account X  X 
Sub Account w/XML X  X X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

Request string

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590

Return

"results" 
"1"

XML VERSION EXAMPLE

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>

extendSubscription

Extends the length of an existing consumer subscription. The ‘extendLength’ parameter is used to extend the subscription by a number of days.

Required (X) and Optional (O) Parameters

manualRemoveclientSubaccusingSubaccreturnXMLextendLength
Main Account  X  X
Main Account w/XML  X X X
Sub Account X   X
Sub Account w/XML X  X

Information Returned

A success or failure code will be returned.

CSV VERSION EXAMPLE

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"

XML VERSION EXAMPLE

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 and Failure Codes

Success Codes
1The requested action was a success.

Error Codes

CodeDescription
0The requested action failed.
-1The arguments provided to authenticate the merchant were invalid or missing.
-2The subscription id provided was invalid or the subscription type is not supported by the requested action.
-3No record was found for the given subscription.
-4The given subscription was not for the account the merchant was authenticated on.
-5The arguments provided for the requested action were invalid or missing.
-6The requested action was invalid
-7There was an internal error or a database error and the requested action could not complete.
-8The IP Address the merchant was attempting to authenticate on was not in the valid range.
-9The merchant’s account has been deactivated for use on the Datalink system or the merchant is not permitted to perform the requested action
-10The merchant has not been set up to use the Datalink system.
-11Subscription is not eligible for a discount, recurring price less than $5.00.
-12The 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.
-15Merchant over refund threshold
-16Merchant over void threshold
-23Transaction limit reached
-24Purchase limit reached

Example 1: XML Version - Cancelled Subscription

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=cancelSubscription&subscriptionId=1000000000&returnXML=1

Description

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.

Response

<?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>

Description

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.

Example 2: CSV Version - Discount Subscription

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900000&username=myusername&password=mypassword&action=discountSubscription&discountAmount=2.00&subscriptionId=0012946984374168

Description

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.

Response

"startPeriod","amount","discounts","discountInterval","type","startDate"
"3","5.00","2","1","LOYALTY","20050222162551"

Description

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.

Special CCBill API Functions:

CCBill API: Cancel Subscription
CCBill API: Advanced Dynamic Upgrades
CCBill API: One Click
CCBill API: Charge by Previous Transaction ID