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.
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 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.
Note: Each rule can be set up on a single subaccount or across all subaccounts.
If you are interested in this advanced feature, please contact merchantsupport@ccbill.com to set up velocity controls according to your business requirements.
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.
The following list describes each field value for Advanced Dynamic Upgrades.
<strong>Example value: 0108113201000024660</strong>
.<strong>Example value: 0000</strong>
.<strong>Example value: 900000</strong>
.<strong>Example value: 0 or 1</strong>
.<strong>Example value: chargeByPreviousTransactionId</strong>
.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:
clientAccnum | userName | Password | clientSubacc | usingSubacc | returnXML | action | |
---|---|---|---|---|---|---|---|
Main Account | ✔ | ✔ | ✔ | ✔ | |||
Main Account w/XML | ✔ | ✔ | ✔ | ✔ | ✔ | ||
Sub Account | ✔ | ✔ | ✔ | ✔ | ✔ | ||
Sub Account w/XML | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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 | ✔ | ✔ | ✔ | ✔ |
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¤cyCode=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"
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>
For a full list of error codes and explanations, please consult the CCBill API Guide.
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.