Subscription Upgrade System user's guide is provided as a technical resource to CCBill Merchants. It is intended for programmers and technicians with advanced programming skills.
The Subscription Upgrade System enables CCBill Merchants to upgrade a consumer subscription to a new subscription. This can be done in the same sub-account or a different sub-account. Upgrades must be pre-configured for the account. The system supports both Credit Card and ACH (Automated Clearing House) upgrades.
The Subscription Upgrade System supports the use of Regional Pricing. By default, the Regional Pricing settings of the account to which the subscription is being upgraded will be used. This setting will be ignored if Regional Pricing is not enabled on the account. For more information on Regional Pricing, consult the Regional Pricing User’s Guide.
The following URL will be used for all upgrade operations using this system:
https://bill.ccbill.com/jpost/upgradeSubscription.cgiValues will be passed into this URL as required.
Upgrades are set up entirely by CCBill Staff. Setup requirements for this functionality are defined below.
The following requirements are needed to utilize the Subscription Upgrade System when upgrading from one subscription type to another:
Upgrades require an upgrade form, which is used by the consumer to request the upgrade. CCBill provides a default upgrade form which can be customized for Credit Card or ACH Upgrades. The upgrade form can be further modified to meet the merchant’s specific needs; however, it must contain all the information on the default upgrade form. It must also be easy to understand and not misleading to the consumer, as well as approved by CCBill management.
The ACH Upgrade form must contain a field where the Bank Account number can be entered and the Credit Card Upgrade form must contain a field where the CVV2 number can be entered.
This section describes the implementation methods for Subscription Upgrades.
To set up an upgrade, CCBill will need the following information for all sub-accounts involved in the upgrade:
Please provide this information to Merchant Support to set up the upgrade. Once complete, Subscription Upgrade functionality can be implemented on the merchant’s site.
Two transmission security options are available for pre-configured upgrades. Merchants must choose between two different authorization methods when sending consumers to the upgrade form.
Either of the following options can be used:
Parameters that are passed to the above mentioned CGI are explained below. Two transmission methods are available:
The encryption method is a one-step process utilizing TripleDES encryption. A TripleDES key must be set up and obtained from CCBill Merchant Support. Once data is encrypted, the encryption string must be Base64 Encoded so that it can be used in a URL. The encryption string will be used as the value for the “enc” parameter. Perform the following steps to obtain the enc value:
The following parameters are required and must be passed in to the following script:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi| Variable Name | Description | Example Value |
|---|---|---|
| clientAccnum | CCBill Merchant Account (of original subscription) | 900100 |
| clientSubacc | CCBill Merchant Subaccount (of original subscription) | 0006 |
| enc | TripleDES encrypted string, Base64 Encoded. Will be inclusive of either the subscriptionId or username. | subscriptionId = 1234567890 OR username = johnDoe (before encryption) |
The following variables are required only when more than one upgrade is configured:
| Variable Name | Description | Example Value |
|---|---|---|
| upgradeClientAccnum | CCBill merchant account to be upgraded. | 900100 |
| upgradeClientSubacc | CCBill Merchant subaccount to be upgraded. | 0006 |
| upgradeTypeId | Subscription type ID to be used for the upgrade. This value identifies the upgrade and is obtained when setting up the upgrade. | 0015 |
These three variables can be omitted if only one upgrade is configured. In this case, that price point will be the one used for the upgrade.
The following example uses the sample values displayed above and a TripleDES key of "8745921457." Optional fields are in bold letters:
<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900100">
<input type="hidden" name="clientSubacc" value="0006">
<input type="hidden" name="enc" value="sysl4wpcOfdF80ghzxJ0H/8YVuBGxA+4wqZqXHS48l8=">
<input type="submit" name="submit" value="Upgrade Subscription">
<strong><input type="hidden" name="upgradeClientAccnum" value="900100">
<input type="hidden" name="upgradeClientSubacc" value="0006">
<input type="hidden" name="upgradeTypeId" value="0015"></strong>
</form>This code will show a form button. When clicked, the upgrade will be performed and the consumer will be sent to the Approval or Denial Redirect page depending on the outcome of the transaction.
The Backend HTTPS Posting method is a two-step process. The first process is the backend post from the merchant’s server to the CCBill upgrade URL. This will return a value indicating whether or not the upgrade can be performed (see Return Values table below).
The second step is to send the consumer to the upgrade form. The consumer must be sent to the upgrade form within 30 minutes of the Backend HTTPS Post. If the consumer is not sent within 30 minutes, the Backend HTTPS Post must be sent again.
Note that when passing in the Subscription ID or username, the value is not an encrypted hash as it would be using the Encryption method defined earlier in this document.
The required parameters sent are:
| Variable Name | Description | Example Value |
|---|---|---|
| clientAccnum | CCBill Merchant Account (of original subscription) | 900100 |
| clientSubacc | CCBill Merchant Subaccount (of original subscription) | 0006 |
| action | The value will always be “allowUpgrade”. This signifies that the incoming request will be preparing the system for a consumer to be allowed to upgrade. | allowUpgrade |
| subscriptionId OR username | The subscriptionId or username that will be allowed to upgrade. | 1234567890 |
The following variables are required only when more than one upgrade is configured:
| Variable Name | Description | Example Value |
|---|---|---|
| upgradeclientAccnum | CCBill merchant account to be upgraded. | 900000 |
| upgradeclientSubacc | CCBill Merchant subaccount to be upgraded. | 0006 |
| upgradeTypeID | Subscription type to be used for the upgrade | 0015 |
These three variables can be omitted if only one upgrade is configured; in this case, that price point will be the one used for the upgrade.
Example using the data above (new lines are used for clarity; optional fields are in bold letters):
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?
clientAccnum=900100&
clientSubacc=0006&
action=allowUpgrade&
subscriptionId=1234567890<strong>&
upgradeClientAccnum=900100&
upgradeClientSubacc=0006&
upgradeTypeId=0015</strong>Note: This post must come from an allowed IP address on the Merchant’s server. The consumer should not be directed to this URL.
Return Values:
The possible return values are included in the table below:
| Value | Description |
|---|---|
| Success | |
| Authorization Denied (Either account is not setup to upgrade, or IP address is not allowed) | |
| Username (username) or Subscription ID (subscriptionId) not provided | |
| No active subscriptions found | |
| Invalid Subscription ID | |
| Internal Error, Contact CCBill |
If a value of "1" is returned, the upgrade is approved and step 2 can begin.
The required parameters sent are:
| Variable Name | Description | Example Value |
|---|---|---|
| clientAccnum | CCBill Merchant Account (of original subscription) | 900100 |
| clientSubacc | CCBill Merchant Subaccount (of original subscription) | 0006 |
| action | The value will always be “upgradeSubscription”. This signifies that the incoming request will show the consumer the upgrade form. | upgradeSubscription |
| subscriptionId OR username | The subscriptionId or username that will be allowed to upgrade. | 1234567890 |
The following variables are required only when more than one upgrade is configured:
| Variable Name | Description | Example Value |
|---|---|---|
| upgradeclientAccnum | CCBill merchant account to be upgraded. | 900100 |
| upgradeclientSubacc | CCBill Merchant subaccount to be upgraded. | 0006 |
| upgradeTypeID | Subscription type to be used for the upgrade | 0015 |
These three variables can be omitted if only one upgrade is configured; in this case, that price point will be the one used for the upgrade.
Example using the data above (optional fields are in bold letters):
<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900100">
<input type="hidden" name="clientSubacc" value="0006">
<input type="hidden" name="action" value="upgradeSubscription">
<input type="hidden" name="subscriptionId" value="1234567890">
<input type="submit" name="submit" value="UpgradeSubscription">
<strong><input type="hidden" name="upgradeClientAccnum" value="900100">
<input type="hidden" name="upgradeClientSubacc" value="0006">
<input type="hidden" name="upgradeTypeId" value="0015"></strong>
</form>Variable values are posted back using the CCBill Background Post system. The following values will be sent to the Approval URL or Denial URL when the upgrade has been performed or denied, respectively:
For more information on the use of Background Post, please consult the CCBill Background Post User’s Guide.