Subscription Upgrade System

Subscription Upgrade System
Copyright© 2016, CCBill, LLC
Subscription Upgrade System
Addendum A: Dynamic Upgrades
v.5, October, 2016
Copyright© 2016, CCBill, LLC
Contents
Introduction....................................................................................................................................... 3
Overview .......................................................................................................................................... 3
Implementation ................................................................................................................................. 3
Code Examples ................................................................................................................................ 4
Encryption Method .............................................................................................................................. 4
Background HTTPS Post Method ........................................................................................................... 4
Postback........................................................................................................................................... 5
Support Contact Information ............................................................................................................ 6
Page 2 of 6
V.3, October, 2016
Copyright© 2016, CCBill, LLC
Introduction
This document is issued as an addendum to the Subscription Upgrade System documentation and
discusses dynamic upgrade functionality. This document is written for developers, technicians, and others
with advanced coding skills.
This document is intended to be used in conjunction with the Subscription Upgrade User’s Guide.
References to the User’s Guide will be made when appropriate.
Overview
Dynamic upgrades, also referred to as pass-through upgrades, allow Merchants to upgrade a consumer
subscription to a new subscription without pre-configuring an option in the system. The upgrade can be
made to the same sub-account or a different sub-account, and can be hard-coded on a page or created
dynamically using a script. Dynamic upgrades are set up entirely by the Merchant but use CCBill’s form
system. In order to use Dynamic Upgrades, the Merchant must contact Merchant Support and request the
feature be enabled.
Dynamic Upgrades support the use of Regional Pricing. By default, the Regional Pricing settings of the
account to which the subscription is being upgraded will be used. Optionally, a Regional Pricing profile
other than the default for the upgraded account can be applied, as explained below. This setting will be
ignored if Regional Pricing is not enabled on the account. For more information on Regional Pricing, please
consult the Regional Pricing User’s Guide.
The system supports both Credit Card and ACH (Automated Clearing House) upgrades.
Implementation
Dynamic upgrades are created by passing variables into a query string. Requests should be sent to the
following CGI script with variable values appended:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi
Dynamic upgrades will be completed as though they were previously set up in the system. Once the
variables have been passed to the above CGI script, the consumer will be redirected to the upgrade form.
To create the upgrade, simply create a price point in the Pricing Area of the CCBill Admin Portal. For help
creating price points, please consult the CCBill help file.
As explained in the Subscription Upgrade User’s Guide, two upgrade methods are available: Encryption
and Background HTTPS Post. The values required for dynamic upgrades should be included along with
the variables listed in the User’s Guide for the desired method. Note that the upgradeTypeId variable is
included in both guides, but is obtained in a different manner than regular (non-dynamic) upgrades.
The following variable values must be passed into the string:
Name
Description
upgradeTypeId
The unique identifier for the price point to which the
subscription will be upgraded. This value can be obtained in
the Pricing Admin section of the CCBill Admin Portal.
4530
Indicates whether the upgrade is a special offer. A value of
zero (0) signifies the upgrade is not a special offer and will
cancel the original subscription. A value of one (1) indicates
a special offer and will not cancel the original subscription.
0 or 1
This value indicates the preferred prorate option. A value of
one (1) prorates the amount and a value of two (2) prorates
the length of time.
1 or 2
specialOffer
prorate
Example Value
Page 3 of 6
V.3, October, 2016
Copyright© 2016, CCBill, LLC
sharedAuthentication
formName
Indicates whether shared authentication is used; a value of
one (1) signifies shared authentication is used and a value
of zero (0) signifies that shared authentication is not used.
0 or 1
The name of the CCBill form used to perform the upgrade.
This value is optional; if no parameter is specified, the
default upgrade form will be used.
1ug
NOTE: If specialOffer is set to zero (0), the prorate parameter must be included. Otherwise, the prorate
parameter is not used.
If you wish to specify a particular Regional Pricing setting, you may optionally pass in the following variable:
Name
Description
regionalPricingId
The unique identifier for the Regional Pricing setting you
wish to use for the upgraded account. This value will be
ignored if Regional Pricing is not enabled on the account.
Example Value
443
The value for regionalPricingId can be obtained by contacting Merchant Support.
Code Examples
As mentioned in the Subscription Upgrade User’s Guide, two methods are available for transmitting
upgrade requests: Encryption and Backend HTTPS Post (consult the User’s Guide for details on these two
methods). For each type, parameters can be passed through the URL or by using hidden HTML form fields.
Some parameters are optional, as noted in the User’s Guide. Each of the following code examples shows
optional parameters in blue.
Encryption Method
If using the Encryption method, pass the above variables in the upgrade request string in addition to those
specified in the User’s Guide. The following URL demonstrates an example of a dynamic upgrade request:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSub
acc=0000&enc=jas2jasdfbJBD19823naISDHASDoiksj923&subscriptionId=0208224109000000496
&upgradeClientSubacc=0001&upgradeClientAccnum=900000&upgradeTypeId=4530&regionalPri
cingId=443
Alternately, the request can be made using hidden HTML form fields, as shown in the next example:
<form method=”POST”
action=”https://bill.ccbill.com/jpost/upgradeSubscription.cgi”>
<input type=”hidden” name=”clientAccnum” value=”900000”>
<input type=”hidden” name=”clientSubacc” value=”0000”>
<input type=”hidden” name=”enc” value=” jas2jasdfbJBDA9823naISDHdSDoiksj923”>
<input type=”hidden” name=”subscriptionId” value=”1234567890”>
<input type=”submit” name=”submit” value=”UpgradeSubscription”>
<input type=”hidden” name=”upgradeClientAccnum” value=”900000”>
<input type=”hidden” name=”upgradeClientSubacc” value=”0001”>
<input type=”hidden” name=”upgradeTypeId” value=”40530”>
<input type=”hidden” name=”regionalPricingId” value=”443”>
</form>
Background HTTPS Post Method
If using the Background HTTPS Post method, dynamic upgrade variables should be passed in during step
two.
Page 4 of 6
V.3, October, 2016
Copyright© 2016, CCBill, LLC
The following code example demonstrates step one of the Backend HTTPS Post using dynamic upgrades:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSub
acc=0000&action=allowUpgrade&subscriptionId=0208724102000000496
The values can also be passed using an HTML form:
<form method=”POST”
action=”https://bill.ccbill.com/jpost/upgradeSubscription.cgi”>
<input type=”hidden” name=”clientAccnum” value=”900000”>
<input type=”hidden” name=”clientSubacc” value=”0000”>
<input type=”hidden” name=”action” value=” allowUpgrade”>
</form>
The string will return a numeric value. A value of “1” means the request is approved (see the User’s Guide
for a complete list of return values). The following example represents code that can be used for step two
of the process:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSub
acc=0000&action=upgradeSubscription&subscriptionId=0208224109000000496&upgradeClien
tSubacc=0001&upgradeClientAccnum=900000&upgradeTypeId=40530&regionalPricingId=443
The values can also be passed using an HTML form:
<form method=”POST”
action=”https://bill.ccbill.com/jpost/upgradeSubscription.cgi”>
<input type=”hidden” name=”clientAccnum” value=”900000”>
<input type=”hidden” name=”clientSubacc” value=”0000”>
<input type=”hidden” name=”action” value=” upgradeSubscription”>
<input type=”hidden” name=”subscriptionId” value=”1234567890”>
<input type=”submit” name=”submit” value=”Upgrade Subscription”>
<input type=”hidden” name=”upgradeClientAccnum” value=”900000”>
<input type=”hidden” name=”upgradeClientSubacc” value=”0001”>
<input type=”hidden” name=”upgradeTypeId” value=”40530”>
<input type=”hidden” name=”regionalPricingId” value=”443”>
</form>
HTML form examples show a button which, when clicked, will pass the parameters into the Subscription
Upgrade system. If successful, the upgrade will be performed.
Postback
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:



originalClientAccnum. The six-digit Merchant account number from where the upgrade
originated.
originalClientSubacc. The four-digit Merchant subaccount number from where the upgrade
originated.
originalSubscriptionId. The subscription ID number of the original subscription.
For more information on the use of Background Post, please consult the CCBill Background Post User’s
Guide.
Page 5 of 6
V.3, October, 2016
Copyright© 2016, CCBill, LLC
Support Contact Information
For any additional questions or assistance, feel free to contact CCBill Merchant Support 365 days a year
or visit our Merchant Support Center.

Phone (TF): 800.510.2859

Hours: 24/7

Fax: 480.449.8801

Email: merchantsupport@ccbill.com

Live Chat: Click Here
Page 6 of 6
V.3, October, 2016
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising