Loading...
 

Subscription Management System (SMS)


Table of Contents

[Show/Hide]

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 Subscription Management System can be utilized.

CCBill Subscription Management System

The subscriptionManagement.cgi script replaces the customCancel.cgi script in the Data Link Extract System. The Subscription Management System has additional features that were not included in the customCancel.cgi.

Before the Subscription Management script can be used your system must be set up to access the CCBill Data Link Extract System.

NOTE: 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 Subscription management system. 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.

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

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

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

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

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=9235
90

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

Description

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

Required (X) and Optional (O) Parameters

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

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

Description

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

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

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

Description

Allows a full or partial refund. Passing in the amount will refund for that amount; please note that refunds cannot be given for an amount higher than that of the initial transaction. Omitting the value will give a full refund in the amount of the initial transaction.

Required (X) and Optional (O) Parameters

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

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

Description

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

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

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

Description

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

Required (X) and Optional (O) Parameters

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

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

Description

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

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

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

Description

Removes a consumer’s ability to access your site.

Required (X) and Optional (O) Parameters

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

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

Description

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

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

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
1 The requested action was a success.

Error Codes

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


Example 1: XML Version - Cancelled Subscription

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=viewSubscriptionStatus&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 Subscrioption

Request

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&clientSubacc=0002&username=myusername&password=mypassword&action=viewSubscriptionStatus&subscriptionId=1000000002

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 Function Addendums: