This document is an addendum to the CCBill API documentation and discusses the Charge by Previous Transaction ID functionality. It provides parameters, descriptions, and examples for developers, technicians, and others with advanced coding skills.
The Charge by Previous Transaction ID functionality enables merchants to offer consumers new transactions without canceling their original subscription. Because this feature does not require the consumer to re-enter payment information on a CCBill payment form, 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 to the subscriptionManagement.cgi script, as explained below.
The system supports credit card transactions with and without 3DS authentication information as well as ACH transactions.
Besides creating new transactions on other subaccounts within the same main account, you can also use the newClientAccnumand newClientSubacc parameters to create transactions on entirely different merchant accounts and subaccounts.
If you are interested in this feature, please get in touch with merchantsupport@ccbill.com to determine if you are a candidate.
CCBill Velocity Controls is an advanced CCBill API feature. It enables you to limit consumer transactions by their number or amount within a specific timeframe.
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. On an individual basis, you allow good loyal customers to continue to make purchases beyond the established limits.
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.
To charge consumers with a previous transaction ID, merchants need to use a query string to pass variables to CCBill's systems. Requests that contain required and optional parameters should be sent to the following CGI script:
https://bill.ccbill.com/jpost/billingApi.cgiThe 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.
Merchants can also submit 3DS SCA information using the chargeByPreviousTransactionId3DS function and associated parameters. CCBillis going to perform the validation and process the transaction to charge the consumer.
To perform a Charge by Previous transaction, pass the following parameters and associated values to CCBill's billingApi:
| PARAMETER | DATA TYPE (Max Lenght) | DESCRIPTION |
|---|---|---|
| action (required) | Function to be performed within the CCBill API. Value: chargeByPreviousTransactionId | |
| subscriptionId (required) | integer (20) | Unique ID of the consumer’s original transaction. Example value: 0108113201000024660 |
| clientAccnum (required) | integer (6) | The six-digit CCBill merchant account number. Example value: 900000 |
| clientSubacc (optional) | integer (4) | The four-digit subaccount number the subscription is related to. You will be authenticated on the specific subaccount if this parameter is provided and not on the main account. The action must pertain to this subaccount; otherwise, it will fail. If you wish to be authenticated on the main account (i.e. your DataLink user was created on the account level) you should omit this parameter. Example value: 0000 |
| usingSubacc (optional) | integer (4) | The parameter specifies a subaccount on which a requested operation will be performed. Use this parameter if you wish to be authenticated on the main account but not on a specific subaccount. |
| username (required) | string (8) | Merchant's Data Link username. Example value: testuser |
| password (required) | string (8) | Merchant's Data Link password. Example value: testpass |
| newClientAccnum (required) | integer (6) | The six-digit CCBill client account number for the new charge. It can be the same as clientAccnum. Example value: 900000 |
| newClientSubacc (required) | integer (4) | The four-digit CCBill client subaccount number for the new charge. It can be the same as clientSubacc. Example value: 0000 |
| sharedAuthentication (required) | boolean | Indicates whether shared authentication is used; a value of 1 signifies that the originating and destination accounts are using the same password file and database. A value of 0 means that shared authentication is not used. |
| currencyCode (optional) | string (3) | Three-digit currency code for the currency used in the transaction. If omitted, the transaction is processed in U.S. dollars (USD) by default. Example value: 840 |
| initialPrice (required) | float (decimal) | Initial transaction price. Example value: 5.00 |
| initialPeriod (required) | integer | The length (in days) of the initial billing period. Example value: 30 |
| recurringPrice (required) | float (decimal) | The amount the consumer will be charged for each recurring bill. For single-billing transactions, set this value equal to 0 Example value: 29.95 |
| recurringPeriod (required) | integer | The length of time between rebills. For single-billing transactions, set this value equal to 0 Example value: 30 |
| rebills (required) | integer | 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 |
| lifeTimeSubscription (optional) | boolean | The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription. |
| returnXML (optional) | boolean (Required if XML is enabled). | If this parameter is passed in with the value 1, you will receive the response in XML format; otherwise, the information is returned in CSV (comma-separated values) format. |
| overrideAffiliate (optional) | integer | Override the affiliate (LAS only) payment on upgrades. A 0 value tells the system not to credit affiliates. A valid Affiliate ID may be passed to specify the Affiliate that should receive the credit, or the parameter may be absent. A blank parameter or invalid Affiliate ID results in an error message. |
| overrideParticipation (optional) | integer | Used with Merchant Connect to override the affiliate payment on upgrades. The 0 value tells the system not to credit any affiliate. A valid PPID indicates the Affiliate that should receive the credit, or the parameter may be absent. A blank parameter or invalid Affiliate ID results in an error message. |
https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0001&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0108113201000024660¤cyCode=840Fields: "approved", "subscriptionId"
Values: "1", "100000000000000000"Fields: "approved", "denialId", "declineCode", "declineText"
Values: "0", "100000000000000000", "15", "declined by bank"Fields: "results"
Values: "-1"https://bill.ccbill.com/jpost/billingApi.cgi??clientAccnum=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0000&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0108113201000024660&returnXML=1<?xml version='1.0' standalone='yes'?>
<results>
<approved>1</approved>
<subscriptionId>100000000000000000</subscriptionId>
</results><?xml version='1.0' standalone='yes'?>
<results>
<approved>0</approved>
<denialId>100000000000000000</denialId>
<declineCode>15</declineCode>
<declineText> declined by bank </declineText>
</results><?xml version='1.0' standalone='yes'?>
<results>-1</results>Pass the following parameters to the billingApi to perform a Charge By Previous Transaction ID function that includes 3DS information:
| PARAMETER | DATA TYPE (Max Lenght) | DESCRIPTION |
|---|---|---|
| action (required) | Function to be performed within the CCBill API. Value: chargeByPreviousTransactionId | |
| subscriptionId (required) | integer (20) | Unique ID of the consumer’s original transaction. Example value: 921201201000001032 |
| clientAccnum (required) | integer (6) | The six-digit CCBill merchant account number. Example value: 900000 |
| clientSubacc (optional) | integer (4) | The four-digit subaccount number the subscription is related to. You will be authenticated on the specific subaccount if this parameter is provided and not on the main account. The action must pertain to this subaccount; otherwise, it will fail. If you wish to be authenticated on the main account (i.e. your DataLink user was created on the account level) you should omit this parameter. Example value: 0000 |
| usingSubacc (optional) | integer (4) | The parameter specifies a subaccount on which a requested operation will be performed. Use this parameter if you wish to be authenticated on the main account but not on a specific subaccount. |
| username (required) | string (8) | Merchant's Data Link username. Example value: testuser |
| password (required) | string (8) | Merchant's Data Link password. Example value: testpass |
| newClientAccnum (required) | integer (6) | The six-digit CCBill client account number for the new charge. It can be the same as clientAccnum. Example value: 900000 |
| newClientSubacc (required) | integer (4) | The four-digit CCBill client subaccount number for the new charge. It can be the same as clientSubacc. Example value: 0000 |
| sharedAuthentication (required) | boolean | Indicates whether shared authentication is used; a value of 1 signifies that the originating and destination accounts are using the same password file and database. A value of 0 means that shared authentication is not used. |
| currencyCode (optional) | string (3) | Three-digit currency code for the currency used in the transaction. If omitted, the transaction is processed in U.S. dollars (USD) by default. Example value: 840 |
| initialPrice (required) | float (decimal) | Initial transaction price. Example value: 5.00 |
| initialPeriod (required) | integer | The length (in days) of the initial billing period. Example value: 30 |
| recurringPrice (required) | float (decimal) | The amount the consumer will be charged for each recurring bill. For single-billing transactions, set this value equal to 0 Example value: 29.95 |
| recurringPeriod (required) | integer | The length of time between rebills. For single-billing transactions, set this value equal to 0 Example value: 30 |
| rebills (required) | integer | 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 |
| lifeTimeSubscription (optional) | boolean | The presence of this variable with a value of 1 indicates that the transaction is a lifetime subscription. |
| returnXML (optional) | boolean (Required if XML is enabled). | If this parameter is passed in with the value 1, you will receive the response in XML format; otherwise, the information is returned in CSV (comma-separated values) format. |
| overrideAffiliate (optional) | integer | Override the affiliate (LAS only) payment on upgrades. A 0 value tells the system not to credit affiliates. A valid Affiliate ID may be passed to specify the Affiliate that should receive the credit, or the parameter may be absent. A blank parameter or invalid Affiliate ID results in an error message. |
| overrideParticipation (optional) | integer | Used with Merchant Connect to override the affiliate payment on upgrades. The 0 value tells the system not to credit any affiliate. A valid PPID indicates the Affiliate that should receive the credit, or the parameter may be absent. A blank parameter or invalid Affiliate ID results in an error message. |
| threedsClientTransactionId (required) | string (36) | |
| threedsAmount (required) | float (decimal) | The amount to be charged (same as initialPrice). Example value: 3.00 |
| threedsCardToken (required) | string (16) | The encrypted cardToken you receive through the 3DS verification process. As we require only the first 16 characters, trim the string to that length before sending it to the CCBill API. Sending a string longer than 16 characters results in an error. Example value: gjeoB5NdJ1r6p0dG |
| threedsVersion (optional) | number(20) | The version of the 3DS protocol to be followed for this specific card and transaction. Available versions are 1.0.2 and 2.1.0 |
| threedsCurrency (optional) | integer (3) | The 3-digit currency code for the currency to be used in this transaction. Example value: 840 |
| threedsStatus (optional) | character (1) | The status of the 3DS verification ('Y', 'N', 'A', etc.) |
| threedsSuccess (required) | boolean | Verification of success or failure. |
| threedsAuthenticationType (optional) | string (36) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1). |
| threedsAuthenticationValue (optional) | string (256) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v2.1). |
| threedsCavv (optional) | string (256) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v1.0.2). |
| threedsCavvAlgorithm (optional) | string (10) | A digital signature that proves that the transaction has been 3DS verified. The signature is obtained through a 3DS verification flow (v1.0.2). |
| threedsEci (required) | integer (2) | An Electronic Commerce Indicator (ECI). Values: '0', '1', '2', '5', '6', or '7'. |
| threedsDsTransId (optional) | string (36) | Directory Server Transaction ID. |
| threedsAcsTransId (optional) | string (36) | Access Control Server Transaction ID. |
| threedsSdkTransId (optional) | string (36) | The 3DS vendor's transaction ID. |
| threedsXid (optional) | string (50) | The transaction identifier (XID) is a unique tracking number set by the merchant for 3DS 1.0. Base encoded 64. |
| threedsError (optional) | string (256) | Error received from the 3DS vendor during the strong customer authentication process. |
| threedsErrorDetail (optional) | string (256) | Error details related to the threedsError. |
| threedsErrorCode (optional) | string (10) | Error code. |
| threedsResponse (optional) | string (400) | The complete response in case of an error. |
https://bill.ccbill.com/jpost/billingApi.cgi?action=chargeByPreviousTransactionId3DS&subscriptionId=921201201000001032&clientAccnum=900000&clientSubacc=0000&newClientAccnum=900000&newClientSubacc=0000&username=testuser&password=testpass&sharedAuthentication=1¤cyCode=840&initialPrice=3.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&lifetimeSubscription=0&threedsClientTransactionId=idtestCase1&threedsAmount=3.00&threedsCardToken=gjeoB5NdJ1r6p0dG&threedsVersion=1.0.2&threedsCurrency=840&threedsStatus=Y&threedsSuccess=1&threedsCavv=cGFzc3dvcmQxMjM0NTZwYXNzd28=&threedsCavvAlgorithm=SHA-256&threedsEci=02&threedsXid=aWQteWo4M3lnb21xZCAgICAgICA=&threedsSdkTransId=testSdkTransId&threedsAcsTransId=testAcsTransId&threedsDsTransId=testDsTransIdFields: "approved", "subscriptionId"
Values: "1", "100000000000000000"Fields: "approved", "denialId", "declineCode", "declineText"
Values: "0", "100000000000000000", "15", "declined by bank"Fields: "results"
Values: "-1"https://bill.ccbill.com/jpost/billingApi.cgi?action=chargeByPreviousTransactionId3DS&subscriptionId=921201201000001032&clientAccnum=900000&clientSubacc=0000&newClientAccnum=900000&newClientSubacc=0000&username=testuser&password=testpass&sharedAuthentication=1¤cyCode=840&initialPrice=3.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&lifetimeSubscription=0&threedsClientTransactionId=idtestCase1&threedsAmount=3.00&threedsCurrency=840&threedsEci=02&returnXML=1<?xml version='1.0' standalone='yes'?>
<results>
<approved>1</approved>
<subscriptionId>100000000000000000</subscriptionId>
</results><?xml version='1.0' standalone='yes'?>
<results>
<approved>0</approved>
<denialId>100000000000000000</denialId>
<declineCode>15</declineCode>
<declineText> declined by bank </declineText>
</results><?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 APIs allow merchants to offer their consumers a convenient upgrade billing solution. Consumers do not have to re-enter their payment details on subsequent purchases. The APIs are managed by the merchant, and the consumers initiate transactions within the merchant’s website or member’s area. While these can be very convenient and valuable tools, they do not come without added risk. The merchant must manage much of the consumer experience, and the APIs are designed to bypass CCBill’s authentication system, V-Scrub.
As a result, the merchant must 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 unique and the controls they implement may differ, the following best practices guide merchants who process 1-Click transactions.