Dynamic Pricing User Guide
Overview
The Dynamic Pricing User Guide is a technical resource intended for programmers, technicians, and others with advanced coding skills.
CCBill’s Dynamic Pricing feature enables merchants to pass variables directly to the signup form and create new pricing options dynamically. Merchants can generate prices on-the-fly using hidden HTML form fields or by including variables in a URL request string.
The passed-in variables define the pricing structure and allow merchants to create both single and recurring prices.
The FlexForms and JPost system utilize different parameters to generate dynamic price points.
Prerequisites
Merchants need to ensure that their merchant account and subaccount are configured for Dynamic Pricing:
- Dynamic Pricing must be enabled on the subaccount used for the transaction.
- A valid Encryption Key is a requirement for creating the formDigest parameter value.
- Dynamic Pricing needs to be enabled on the payment form (FlexForms System only).
Unsure if you are meeting these requirements? Please contact CCBill Merchant Support to check your Dynamic Pricing system settings.
Dynamic Pricing Parameters - FlexForms
The base URL for sending Dynamic Pricing requests when using FlexForms is:
https://api.ccbill.com/wap-frontflex/flexformsThe FlexForms system awards each payment flow a unique Flex ID. The Flex ID tells the system which payment form to use when displaying dynamic prices.
The Flex ID is an integral part of the dynamic pricing string and is the first value that must be included in each Dynamic Pricing request:
https://api.ccbill.com/wap-frontflex/flexforms/687fa3e0-e60d-4466-88e2-181fa56dd6a9Additional variables are appended to the base URL and the Flex ID. The set of variables passed to the form depends on the type of transaction and whether the merchant wants to create a single or recurring price point.
Single Billing Variables
| PARAMETER | DESCRIPTION | EXAMPLE VALUE |
|---|---|---|
| clientSubacc | An integer representing the 4-digit merchant subaccount number. | 0000 |
| initialPrice | A decimal value (two decimals) representing the initial price. | 10.00 |
| initialPeriod | An integer representing the length, in days, of the initial billing period. By default, the value for non-recurring prices is between 2 and 365. | 30 |
| currencyCode | An integer representing the 3-digit currency code that will be used for the transaction. | USD - 840 EUR - 978 GBP - 826 CAD - 124 AUD - 036 JPY - 392 |
| formDigest | An MD5 hash of payment parameters and a unique encryption key. Explore our detailed guide on how to create formDigest values for FlexForms. | a7459445d0e5dc0963fe736dc5cf900b |
Code Examples
An example of a non-recurring FlexForms Dynamic Price request includes the following variables:
https://api.ccbill.com/wap-frontflex/flexforms/687fa3e0-e60d-4466-88e2-181fa56dd6a9?clientSubacc=0000&initialPrice=10.00&initialPeriod=30¤cyCode=840&formDigest=a7459445d0e5dc0963fe736dc5cf900bYou can also call specific payment flows and pass the dynamic pricing variables using the CCBill Web Widget:
<div class=”ccbillWidgetContainer”>
<script type="text/javascript" class="CCBillWidget687fa3e0-e60d-4466-88e2-181fa56dd6a9_109" src="https://images.ccbill.com/flexforms/ccbill-widget-live.js">
{ "parameters" :
{
"clientSubacc" : "0000",
"initialPrice" : "10.00",
"initialPeriod" : "30",
"currencyCode" : "840",
"formDigest" : "48f0b12e4307e64edb781c479665c899"
}
}
</script>
</div>Recurring Price Variables
| PARAMETER | DESCRIPTION | EXAMPLE VALUE |
|---|---|---|
| clientSubacc | An integer representing the 4-digit merchant subaccount number. | 0000 |
| initialPrice | A decimal value (two decimals) representing the initial price. | 10.00 |
| initialPeriod | An integer representing the length, in days, of the initial billing period. By default, the value for non-recurring prices is between 2 and 365. | 30 |
| recurringPrice | A decimal value (two decimals) representing the recurring price. | 10.00 |
| recurringPeriod | An integer representing the length, in days, of the recurring billing period. The default values for recurring prices are 30, 60, and 90. | 30 |
| numRebills | An integer number of rebills. The default value for recurring prices is 99. | 99 |
| currencyCode | An integer representing the 3-digit currency code that will be used for the transaction. | USD - 840 EUR - 978 GBP - 826 CAD - 124 AUD - 036 JPY - 392 |
| formDigest | An MD5 hash of payment parameters and a unique encryption key. Explore our detailed guide on how to create formDigest values for FlexForms. | 48f0b12e4307e64edb781c479665c899 |
Code Examples
An example of a non-recurring FlexForms Dynamic Price request includes the following variables:
https://api.ccbill.com/wap-frontflex/flexforms/687fa3e0-e60d-4466-88e2-181fa56dd6a9?clientSubacc=0000&initialPrice=10.00&initialPeriod=30&recurringPrice=10.00&recurringPeriod=30&numRebills=99¤cyCode=840&formDigest=48f0b12e4307e64edb781c479665c899You can also call specific payment flows and pass the dynamic pricing variables using the CCBill Web Widget:
<div class=”ccbillWidgetContainer”>
<script type="text/javascript" class="CCBillWidget687fa3e0-e60d-4466-88e2-181fa56dd6a9_109" src="https://images.ccbill.com/flexforms/ccbill-widget-live.js">
{ "parameters" :
{
"clientSubacc" : "0000",
"initialPrice" : "10.00",
"initialPeriod" : "30",
"recurringPrice" : "10.00",
"recurringPeriod" : "30",
"numRebills" : "99",
"currencyCode" : "840",
"formDigest" : "48f0b12e4307e64edb781c479665c899"
}
}
</script>
</div>Response Digest Value
Merchants who use Dynamic Pricing and Webhooks receive a dynamicPricingValidationDigest value after a successful or failed transaction event.
If you are using the Background Post System, you will receive the responseDigest value instead.
This value is an MD5 hash of transaction results which can be used to verify that the response was received properly by CCBill.
Approved Transactions
The responseDigest or dynamicPricingValidationDigest values for approved transactions are generated the same way. CCBill’s system creates a single string from the following values and hashes (MD5) them:
| VALUE | DESCRIPTION |
|---|---|
| subscriptionId | The unique subscription ID number for the subscription. |
| 1 | This value is simply the number 1 (one), used to show the transaction was approved. |
| salt | The same encryption key used to generate the formDigest value. You can retrieve the Encryption/Salt Key from the CCBill Admin. |
These values will be sent to the Approval Post URL or Webhooks URL configured for NewSaleSuccess.
Denied Transactions
The responseDigest or dynamicPricingValidationDigest values for denied transactions are generated the same way. CCBill’s system creates a single string from the following values and hashes (MD5) them:
| VALUE | DESCRIPTION |
|---|---|
| subscriptionId | The unique subscription ID number for the subscription. |
| 0 | This value is simply the number 0 (zero), used to show the transaction was denied. |
| salt | The same encryption key used to generate the formDigest value. You can retrieve the Encryption/Salt Key from the CCBill Admin. |
These values will be sent to the Denial Post URL, or the URL configured for newSaleFailures in Webhooks.
CCBill’s system returns error codes if a dynamic pricing option cannot be generated on the payment form. Find out how to fix Dynamic Pricing error codes if that happens.
Dynamic Pricing Parameters (JPost Payment Forms)
The base URL for sending Dynamic Pricing requests when using JPost forms is:
https://bill.ccbill.com/jpost/signup.cgiAdditional variables are appended to the base URL. The set of variables passed to the form depends on the type of transaction and whether the merchant wants to create a single or recurring price point.
Single Billing Variables
| PARAMETER | DESCRIPTION | EXAMPLE VALUE |
|---|---|---|
| clientAccnum | An integer value representing the 6-digit merchant account number. | 900000 |
| clientSubacc | An integer representing the 4-digit merchant subaccount number. | 0000 |
| formName | The name of the JPost payment form. | 104cc |
| formPrice | A decimal value (two decimals) representing the initial price. | 10.00 |
| formPeriod | An integer representing the length, in days, of the initial billing period. By default, the value for non-recurring prices is between 2 and 365. | 30 |
| currencyCode | An integer representing the 3-digit currency code that will be used for the transaction. | USD - 840 EUR - 978 GBP - 826 CAD - 124 AUD - 036 JPY - 392 |
| formDigest | An MD5 hash of payment parameters and a unique encryption key. Explore our detailed guide on how to create formDigest values for FlexForms. | a7459445d0e5dc0963fe736dc5cf900b |
Code Examples
An example of a non-recurring Dynamic Price request in JPost includes the following variables:
https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0000&formName=104cc&formPrice=10.00&formPeriod=30¤cyCode=840&formDigest=a7459445d0e5dc0963fe736dc5cf900bVariables can also be passed using hidden fields in an HTML form. The following example shows possible code for a button that will take the consumer to the signup form:
<form id="myForm" method="post" action="https://bill.ccbill.com/jpost/signup.cgi">
<input type="hidden" name="clientAccnum" value="900000">
<input type="hidden" name="clientSubacc” value="0000">
<input type="hidden" name="formName” value="104cc">
<input type="hidden" name="formPrice” value="10.00">
<input type="hidden" name="formPeriod” value="30">
<input type="hidden" name="currencyCode" value="840">
<input type="hidden" name="formDigest" value="a7459445d0e5dc0963fe736dc5cf900b">
<input type="submit" value="Join Now!">
</form>Recurring Billing Variables
| PARAMETER | DESCRIPTION | EXAMPLE VALUE |
|---|---|---|
| clientAccnum | An integer value representing the 6-digit merchant account number. | 900000 |
| clientSubacc | An integer representing the 4-digit merchant subaccount number. | 0000 |
| formName | The name of the payment form. | 211cc |
| formPrice | A decimal value (two decimals) representing the initial price. | 10.00 |
| formPeriod | An integer representing the length, in days, of the initial billing period. By default, the value for non-recurring prices is between 2 and 365. | 30 |
| formRecurringPrice | A decimal value (two decimals) representing the recurring price. | 10.00 |
| formRrecurringPeriod | An integer representing the length, in days, of the recurring billing period. The default values for recurring prices are 30, 60, and 90. | 30 |
| formRebills | An integer number of rebills. The default value for recurring prices is 99. | 99 |
| currencyCode | An integer representing the 3-digit currency code that will be used for the transaction. | USD - 840 EUR - 978 GBP - 826 CAD - 124 AUD - 036 JPY - 392 |
| formDigest | An MD5 hash of payment parameters and a unique encryption key. Explore our detailed guide on how to create formDigest values for FlexForms. | 48f0b12e4307e64edb781c479665c899 |
Code Examples
The following example shows the data being passed through the URL string:
https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0000&formName=211cc&formPrice=10.00&formPeriod=30&formRecurringPrice=10.00&formRecurringPeriod=30¤cyCode=840&formRebills=99&formDigest=a7459445d0e5dc0963fe736dc5cf900bVariables can also be passed using hidden fields in an HTML form. The following example shows possible code for a button that will take the consumer to the signup form:
<form id="myForm" method="post" action="https://bill.ccbill.com/jpost/signup.cgi">
<input type="hidden" name="clientAccnum" value="900000">
<input type="hidden" name="clientSubacc” value="0000">
<input type="hidden" name="formName” value="211cc">
<input type="hidden" name="formPrice” value="10.00">
<input type="hidden" name="formPeriod” value="30">
<input type="hidden" name="formRecurringPrice" value="10.00">
<input type="hidden" name="formRecurringPeriod" value="30">
<input type="hidden" name="currencyCode" value="840">
<input type="hidden" name="formRebills" value="99">
<input type="hidden" name="formDigest" value="a7459445d0e5dc0963fe736dc5cf900b">
<input type="submit" value="Join Now!">
</form>Response Digest Value
Merchants who use Dynamic Pricing and Webhooks receive a dynamicPricingValidationDigest value after a successful or failed transaction event.
If you are using the Background Post System, you will receive the responseDigest value instead.
This value is an MD5 hash of transaction results which can be used to verify that the response was received properly by CCBill.
Approved Transactions
The responseDigest or dynamicPricingValidationDigest values for approved transactions are generated the same way. CCBill’s system creates a single string from the following values and hashes (MD5) them:
| VALUE | DESCRIPTION |
|---|---|
| subscriptionId | The unique subscription ID number for the subscription. |
| 1 | This value is simply the number 1 (one), used to show the transaction was approved. |
| salt | The same encryption key used to generate the formDigest value. You can retrieve the Encryption/Salt Key from the CCBill Admin. |
These values will be sent to the Approval Post URL or Webhooks URL configured for NewSaleSuccess.
Denied Transactions
The responseDigest or dynamicPricingValidationDigest values for denied transactions are generated the same way. CCBill’s system creates a single string from the following values and hashes (MD5) them:
| VALUE | DESCRIPTION |
|---|---|
| subscriptionId | The unique subscription ID number for the subscription. |
| 0 | This value is simply the number 0 (zero), used to show the transaction was denied. |
| salt | The same encryption key used to generate the formDigest value. You can retrieve the Encryption/Salt Key from the CCBill Admin. |
These values will be sent to the Denial Post URL, or the URL configured for newSaleFailures in Webhooks.
CCBill’s system returns error codes if a dynamic pricing option cannot be generated on the payment form. Find out how to fix Dynamic Pricing error codes if that happens.