CCBill API: Advanced Dynamic Upgrades

Introduction

This document is issued as an addendum to the CCBill API documentation and discusses Advanced Dynamic Upgrade functionality. This document is written for developers, technicians, and others with advanced coding skills.

Overview

Advanced Dynamic Upgrades allow clients to upgrade consumers’ past subscriptions to a new subscription without pre-configuring a price in the system. Advanced Dynamic Upgrades can be made to the same subaccount or a different subaccount and are set up entirely by the client. Because Advanced Dynamic Upgrades do not require the consumer to re-enter payment information, the client is responsible for hosting the terms of the upgrade being offered.

Advanced Dynamic Upgrades do not require pre-configured upgrades to be set up in CCBill’s system. However, price points can be created in the Pricing Area of the CCBill Webmaster Admin, to which the upgrade will occur.

The system supports both Credit Card and ACH (Automated Clearing House) upgrades.

Regional Pricing Support

Advanced Dynamic Upgrades can support Regional Pricing, with an additional step. Two requests will be made; the initial upgrade request calculates the new price and the second request actually performs the transaction. This process is described in detail later in this document.

CCBill Velocity Controls Feature

CCBill Velocity Controls is an advanced CCBill API feature, and it enables you to limit customer transactions by the number of transactions and/or by cash amount of transactions within a specific time-frame. This means that you can set the number of transactions for a specific customer within a given period of time.

Rules apply to all payment types, and each customer is assigned a unique ID based on their financial information and security background. By setting up CCBill Velocity Controls, you limit the chances of fraud and, on an individual basis, you allow good loyal customers to continue to make purchases beyond the established limits.

If you are interested in this advanced feature, please contact merchantsupport@ccbill.com to set up velocity controls according to your business requirements.

Implementation

Advanced Dynamic Upgrades are created by passing parameters into a query string. Requests should be sent to the following CGI script with variable values appended:

https://bill.ccbill.com/jpost/billingApi.cgi

The upgrade will be performed pending validation from CCBill. Depending on the result of the validation, different results will be returned. Results can be returned in either comma-separated value (CSV) format or XML format. Examples of request strings and their potential output are shown below.

Field Explanations

The following list describes each field value for Advanced Dynamic Upgrades.

• subscriptionId. The unique identifier for the consumer’s subscription. Example value: 0108113201000024660
• upgradeTypeId. Valid Subscription Type ID for the upgrade. This value is numeric and varies in length. This value is the unique price point identifier that can be found in the Pricing Admin area of the CCBill Webmaster Admin. (Note that this value can be omitted if you wish to use the default upgrade price. Consult the CCBill Pricing Admin help page for more information on default upgrades.) Example value: 35160
• upgradeClientAccnum. The six-digit CCBill client account number being upgraded to. Example value: 900000
• upgradeClientSubacc. The four-digit CCBill client subaccount number being upgraded to. Example value: 0000
• currencyCode. The value represents a three-digit currency code (ISO 4217 standard) for the currency used in the transaction.
• specialOffer. 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. In both cases, the new subscription will be given a different Subscription ID number. Example value: 0 or 1
• prorate. 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. Example value: 1 or 2
• sharedAuthentication. Indicates whether shared authentication is used; a value of one (1) signifies the originating and destination accounts are using the same password file and/or database, and a value of zero (0) signifies that shared authentication is not used. Example value: 0 or 1
• action. This value determines the type of upgrade to be used. If using Regional Pricing, the value will be set to getUpgradeDetails. If NOT using Regional Pricing, the value will be set to upgradeSubscription.
• overrideAffiliate. Used with the Legacy Affiliate System (LAS) only, this parameter is used to override the affiliate payment on upgrades. A value of 0 tells the system not to credit any affiliate, a valid LAS Affiliate ID may be passed in to indicate the Affiliate that should receive the credit, or the parameter may be absent. Passing in a blank parameter or invalid Affiliate ID will result in an error message.
• overrideParticipation. Used with Web Marketing Service (WMS) only, this parameter is used to override the affiliate payment on upgrades. A value of 0 tells the system not to credit any affiliate, a valid WMS PPID may be passed in to indicate the Affiliate that should receive the credit, or the parameter may be absent. Passing in a blank parameter or invalid Affiliate ID will result in an error message.

Required (✔) and Optional Parameters

All parameters explained above are required in addition to the required fields listed in the main CCBill API documentation. The following table indicates which fields are required or optional:

Main CCBill API Parameters

	clientAccnum	userName	Password	clientSubacc	usingSubacc	returnXML	action
Main Account	✔	✔	✔				✔
Main Account w/XML	✔	✔	✔			✔	✔
Sub Account	✔	✔	✔	✔			✔
Sub Account w/XML	✔	✔	✔	✔		✔	✔

Additional Upgrade Parameters

	subscriptionId	upgradeTypeId	upgradeClientAccnum	upgradeClientSubacc
Main Account	✔	✔	✔	✔
Main Account w/XML	✔	✔	✔	✔
Sub Account	✔	✔	✔	✔
Sub Account w/XML	✔	✔	✔	✔
Main Account w/Special Offer	✔	✔	✔	✔
Main Account w/XML	✔	✔	✔	✔
and Special Offer	✔	✔	✔	✔
Sub Account w/Special Offer	✔	✔	✔	✔
Sub Account w/XML and Special Offer	✔	✔	✔	✔

	specialOffer	prorate	overrideAffiliate	overrideParticipation
Main Account	✔	✔
Main Account w/XML	✔	✔
Sub Account	✔	✔
Sub Account w/XML	✔	✔
Main Account w/Special Offer	✔
Main Account w/XML	✔
and Special Offer	✔
Sub Account w/Special Offer	✔
Sub Account w/XML and Special Offer	✔

Code Examples

The following code examples use the upgradeSubscription action, which does not support Regional Pricing.

CVS Version Example

Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900100&username=testUser&password=testPass&action=upgradeSubscription&subscriptionId=18902345789012343781&currencyCode=840&upgradeTypeId=14&upgradeClientAccnum=900100&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=1

Results Sent (for approved transactions):

Fields: "approved", "subscriptionId" 
Values: "1", "100000000000000000"

Results Sent (for denied transactions):

Fields: "approved", "denialId", "declineCode", "declineText" 
Values: "0", "100000000000745921", "15", "declined by bank"

Results Sent (when an error occurs)

Fields: "results" 
Values: "-1"

XML Version Example

Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900100&username=testUser&password=testPass&action=upgradeSubscription&subscriptionId=0108114301000018799&currencyCode=840&upgradeTypeId=14&upgradeClientAccnum=900100&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=1&returnXML=1

Results Sent (for approved transactions)

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>1</approved> 
<subscriptionId>100000000000000000</subscriptionId> 
</results>

Results Sent (for denied transactions):

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>0</approved> 
<denialId>100000000000000000</denialId> 
<declineCode>15</declineCode> 
<declineText> declined by bank </declineText> 
</results>

Results Sent (when an error occurs)

<?xml version='1.0' standalone='yes'?> 
<results>-1</results>

Implementation Using Regional Pricing

To use Regional Pricing with Advanced Dynamic Upgrades, two requests must be made. The first request is a standard Advanced Dynamic Upgrade request using the getUpgradeDetails action. The first request only returns data; no transaction is processed until the second request is sent. The first request will return data to be used in the second request as described below.

The second request will be sent using the chargeByPreviousTransactionId action. This request processes the upgrade transaction.

Return Data

The first request returns the following values:

• initialPrice. The price of the initial bill.
• recurringPrice. The recurring price for each rebill.
• initialPeriod. The length of the initial period (in days).
• recurringPeriod. The length of time (in days) between rebills.
• rebills. Total number of times the subscription will rebill. A value of “99” means the subscription will rebill indefinitely.
• initialPriceDescription. Text description of the initial price.
• recurringPriceDescription. Text description of the recurring price.
• currencyCode. Three-digit currency code in which the transaction is processed.
• processTransactionUrl. The full string for the second request.

Once the data has been passed back, submit the processTransactionUrl value as the second request. This will process the transaction.

Code Examples

The following code examples use the getUpgradeDetails action to support Regional Pricing. Because this action requires a second request to actually process the transaction, code examples for both requests are provided.

Note that the first request returns a value called processTransactionUrl which contains the exact string needed for the second request. This URL will process the actual transaction. The second request returns data describing the results of the transaction.

CVS Version Example

First Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=getUpgradeDetails&prorate=2&subscriptionId=0908267201000000008&upgradeClientAccnum=999999&upgradeClientSubacc=0000&currencyCode=840&specialOffer=1&sharedAuthentication=0&upgradeTypeId=0000060948

Data Returned from First Request

Fields: "currencyCode","recurringPriceDescription","initialPriceDescription","initialPeriod",
"initialPrice","recurringPrice","recurringPeriod","processTransactionUrl","rebills"
Values: "840","","$19.95(USD) for 30 days","30","19.95","12.95","30", "[link below]","99"

Second Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=chargeByPreviousTransactionId&subscriptionId=0908267201000000008&newClientAccnum=999999&newClientSubacc=0000&specialOffer=1&sharedAuthentication=0&currencyCode=840&initialPrice=19.95&initialPeriod=30&recurringPrice=12.95&recurringPeriod=30&rebills=99

Results Sent from Second Request (for approved transactions)

Fields: "approved", "subscriptionId" 
Values: "1", "1234567890"

Results Sent from Second Request (for denied transactions):

Fields: "approved", "denialId", "declineCode", "declineText" 
Values: "0", "100000000000000000", "15", "declined by bank"

Results Sent from Second Request (when an error occurs)

Fields: "results" 
Values: "-1"

XML Version Example

First Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=getUpgradeDetails&prorate=2&subscriptionId=0908267201000000008&currencyCode=840&upgradeClientAccnum=999999&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=0&upgradeTypeId=0000060948

Data Returned from First Request

<results> 
<currencyCode>840</currencyCode> 
<initialPeriod>30</initialPeriod> 
<initialPrice>19.95</initialPrice> 
<initialPriceDescription>$19.95(USD) for 30 days</initialPriceDescription> 
<processTransactionUrl>[link below]</processTransactionUrl> 
<rebills>99</rebills> 
<recurringPeriod>30</recurringPeriod> 
<recurringPrice>12.95</recurringPrice> 
<recurringPriceDescription/>
</results>

Second Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=chargeByPreviousTransactionId&subscriptionId=0908267201000000008&newClientAccnum=999999&newClientSubacc=0000&specialOffer=1&sharedAuthentication=0&currencyCode=840&initialPrice=19.95&initialPeriod=30&recurringPrice=12.95&recurringPeriod=30&rebills=99

Results Sent from Second Request (for approved transactions):

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>1</approved> 
<subscriptionId>100000000000000000</subscriptionId> 
</results>

Results Sent from Second Request (for denied transactions):

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>0</approved> 
<denialId>100000000000000000</denialId> 
<declineCode>15</declineCode> 
<declineText> declined by bank </declineText> 
</results>

Results Sent from Second Request (when an error occurs):

<?xml version='1.0' standalone='yes'?> 
<results>-1</results>

Error Codes

Regardless of which action is used, numeric codes will be returned if the request fails due to an error. For a full list of error codes and explanations, please consult the CCBill API Guide.

Best Practices

CCBill’s 1-Click API’s allow merchants to offer their customers with a convenient upgrade billing solution which enables customers from having to re-enter their payment details on subsequent purchases. The API’s are managed by the merchant and transactions are initiated by the consumers within the merchant’s website or member’s area. While these can be very convenient and useful tools, they do not come without added risk. The merchant is required to manage much of the consumer experience, and the API’s are designed to bypass CCBill’s authentication system, V-Scrub.

As a result, it is imperative for the merchant to understand their responsibilities and implement a system of controls designed to manage the consumer experience and minimize the risk of chargebacks and revenue loss.

While each merchant’s business model is inherently unique, and controls they implement may differ, the following best practices act as a guide for merchants who process 1-Click transactions.

1. Consumer Disclosure: Increase consumer education and awareness throughout the payment process and website.
   • Clear Pricing Descriptions throughout the upgrade process. Prices should include the proper currency, accurate value of credits/tokens, and should display any other terms relevant to the purchase.
   • The purchase button should be action oriented to ensure the consumer is aware they are initiating a purchase.
   • Clear Approval/Denial Messaging: The consumer should be made aware of the approval/denial immediately within the member’s area, and confirmation emails should be sent.
   • 1-Click Environment Education: Consumers need to understand they can initiate charges against their account with the click of a button. In addition to clear messaging, some merchants may want to ensure their customers can opt-in and opt-out of the 1-click environment.
   • Refund Policy: The merchant’s refund policy should be easy to locate on the website, and should clearly instruct consumers what issues may result in a refund if they run into issues with their purchase.
   • Billing Descriptors should reinforced in the upgrade process and in confirmation emails. The merchant’s support page should also provide reinforcement of the descriptors.
   • Support Information should be prevalent throughout the entire website to ensure customers can contact support for any issue with their service.
2. Velocity Controls: The 1-click API’s do not limit transaction volume, and the transactions are not scrubbed for risk.
   • New Customers vs. Existing: Treat new customers with added scrutiny by limiting their transactions in a given period of time. For example, a new customer should only be allowed to purchase 4 transactions within the initial 30 days.
   • Existing Customers who have proven to be low risk can also be asked to revalidate their data after a higher number of transactions. For example, the customer has to opt back into the 1-click agreement after 20 transactions.
3. Affiliate/Traffic Source Monitoring: The merchant should report refund and chargeback activity to their traffic sources to ensure they are being appropriately managed from month to month.
   • Affiliates/Traffic sources with high chargeback rates should be terminated.
   • Delay payouts with new affiliate/traffic sources to ensure transactions can be reviewed prior to paying the affiliate. If high risk patterns are detected, delay the payout to ensure refunds and chargebacks can clear.
     Note: This may take up to 120 days
4. Model/Cam Studio Monitoring: The merchant should report refund and chargeback activity to their model and cam studio sources to ensure they are being appropriately managed from month to month.
   • Model/Cam Studio sources with high chargeback rates should be terminated.
   • Delay payouts with new model/cam studio sources to ensure transactions can be reviewed prior to paying the affiliate. If high risk patterns are detected, delay the payout to ensure refunds and chargebacks can clear.
     Note: This may take up to 120 days
5. Post Transaction Monitoring: The merchant should verify a consumer if higher risk patterns or behavior is detected.
   • Review customers' credit/token usage patterns. New customers who do not use tokens or credits upon payment should be considered high risk.
   • Review IP’s associated with logins and compare to purchase IP’s. Differences should be considered high risk.
   • High dollar amounts spent in shorter periods of time should be reviewed to ensure legitimacy.