CCBill API: Charge by Previous Transaction ID

Introduction

This document is issued as an addendum to the CCBill API documentation and discusses Charge by Previous Transaction ID functionality. This document is written for developers, technicians, and others with advanced coding skills.

Overview

Charging by previous transaction ID allows clients to offer special offers to consumers without using CCBill signup forms. This will create a new transaction and not cancel the original subscription. Because this feature does not require the consumer to re-enter payment information, the client is responsible for hosting the terms of the offer.

Charging by previous transaction ID does not require the offer to be previously set up in CCBill’s system. Offers are created dynamically by passing variables into the subscriptionManagement.cgi script as explained below.

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

While this feature allows you to create new transactions on other subaccounts within a main account by using a previous transaction ID, a customization may be available that will allow you to move the transaction to an entirely different account and other subaccounts belonging to different main accounts by passing in different numbers for the newClientAccnum and newClientSubacc fields.

If you are interested in this feature, please contact merchantsupport@ccbill.com to determine if you are a candidate.

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

Charging by previous transaction ID is done by passing variables into a query string. Requests should be sent to the following CGI script with parameters appended:

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

The consumer will be charged 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 later in this document.

Field Explanations

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

• subscriptionId. The unique identifier for the consumer’s subscription. <strong>Example value: 0108113201000024660</strong>.
• newClientAccnum. The four-digit CCBill client subaccount number for the new charge. <strong>Example value: 0000</strong>.
• newClientSubacc. The six-digit CCBill client account number being upgraded to. <strong>Example value: 900000</strong>.
• sharedAuthentication. 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. <strong>Example value: 0 or 1</strong>.
• action. This value is always set to chargeByPreviousTransactionId. <strong>Example value: chargeByPreviousTransactionId</strong>.
• currencyCode (optional). The three-digit currency code for the currency in which the transaction will be processed. This value is optional. If omitted, the transaction will be processed in U.S. dollars (USD).
• initialPrice. The initial (first) price charged for the first billing period.
• initialPeriod. The length (in days) of the initial billing period.
• lifeTimeSubscription. Indicates a subscription being made as a lifetime subscription. The presence of this variable with a value of 1 (one) indicates that the transaction is a lifetime subscription.
• recurringPrice. The amount the consumer will be charged for each recurring bill. For single-billing transactions, set this value equal to 0 (zero).
• recurringPeriod. The length of time between rebills. For single-billing transactions, set this value equal to 0 (zero).
• rebills. The total number of times the subscription will rebill. For unlimited rebills, set this value equal to 99. For single-billing transactions, set this value equal to 0 (zero).
• 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 Parameters

	subscriptionId	initialPrice	initialPeriod	newClientAccnum	newClientSubacc	currencyCode
Main Account	✔	✔	✔	✔	✔
Main Account w/XML	✔	✔	✔	✔	✔
Sub Account	✔	✔	✔	✔	✔
Sub Account w/XML	✔	✔	✔	✔	✔

	lifeTimeSubscription	recurringPrice	recurringPeriod	rebills	overrideAffiliate	overrideParticipation
Main Account		✔	✔	✔	✔
Main Account w/XML		✔	✔	✔	✔
Sub Account		✔	✔	✔	✔
Sub Account w/XML		✔	✔	✔	✔

CVS Version Example

Request String

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0005&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0102751901000023384&currencyCode=840

Results Sent (for approved transactions)

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

Results Sent (for denied transactions):

Fields: "approved", "denialId", "declineCode", "declineText" 
Values: "0", "100000000000000000", "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=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0005&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0102751901000023384&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>

Error Codes

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.