Background Post
This document is provided as a technical resource to CCBill merchants. It discusses the features and implementation of the CCBill Background Post system. This document is intended to be read by programmers, technicians, and others with advanced coding skills.
Overview
CCBill Background Post is a method of passing data between the merchant’s system and CCBill’s system. Background Post essentially serves two purposes:
- Pass consumer data into the CCBill signup form. This can be used to pre-fill consumer data on the form or pass custom tracking parameters to be sent to the Approval/Denial Post URLs (see below). A list of standard CCBill system variables, used for pre-filling consumer data, is provided later in this document.
- Pass data to an Approval Post URL or Denial Post URL, depending on the outcome of the transaction. The Approval and Denial URLs are custom-coded scripts that capture returned post data from CCBill and process it according to the coding of the script. Approval and Denial Post URLs are coded by the merchant and are required to use the Background Post system. This guide will discuss potential applications of these URLs. For more information on setting your Approval and Denial Post URLs, please consult the CCBill help file.
These two applications of the Background Post system are mutually exclusive and neither is required to use the other.
TLS Support
Background Post supports TLS 1.2 security protocol. If you are experiencing difficulties and not receiving posts from CCBill, please check which TLS protocol you’re using.
Passing Variables to the Signup Form
Variables can be passed to the signup form in order to pre-fill consumer information. This can be implemented for the purpose of multi-part forms, custom tracking, and other implementations. Variables are passed to the signup form from the page preceding it through the use of an HTML form, or by passing in the variables through the URL string. Code examples are given below.
Custom tracking variables can also be sent to the form. These values will be posted back using Background Post when the transaction is complete. To define these variables, simply specify a variable name and a value in the same manner as the other variables being passed.
To pre-fill the form, you must first generate HTML code for the form within the CCBill Admin. (For more information on how to generate this code, please consult the CCBill help file.) After generating your code, optional custom tracking variables can be added manually by creating additional HTML form fields or passing the additional variables into the URL string, depending on the chosen submission method.
The following example shows basic HTML button code, with two custom variables added. The button created will, when clicked, take the consumer to the CCBill signup form while passing in the two custom variables:
<form action='https://bill.ccbill.com/jpost/signup.cgi' method=POST> <input type=hidden name=clientAccnum value='900000'> <input type=hidden name=clientSubacc value='0001'> <input type=hidden name=formName value='13cc'> <input type=hidden name=language value='English'> <input type=hidden name=allowedTypes value='0000003361:840,0000004657:840,0000060748:840,0000060750:840,0000060752:840' > <input type=hidden name=subscriptionTypeId value='0000004657:840'> <input type=hidden name=customVarName1 value=customVarValue1> <input type=hidden name=customVarName2 value=customVarValue2> <input type=submit name=submit value='Join Now'> </form>
customVarName1 and customVarName2 are only example names and can be anything you choose. The values are also an example.
You can use a text link instead of a button. The following example shows how to do this using data identical to the previous form example:
https://bill.ccbill.com/jpost/signup.cgi?clientAccnum=900000&clientSubacc=0001&formName=11wc&language=English&allowedTypes=0000003761:840,0000004607:840,0000060248:840,0000063750:840,0000060752:840&subscriptionTypeId=0000004657:840&customVarName1=customVarValue1&customVarName2=customVarValue2
Both methods serve the same purpose and either can be used.
Information can also be passed to the CCBill signup form using dynamic variables in a custom script. A custom HTML form can call the script, which then sends the variables to the CCBill signup form. The data flows in this path:
The form you create will pass data entered by the consumer to the next form, which will then pass the variables to the CCBill signup form. Upon completion of the transaction, data will be sent to the Approval or Denial Post URL.
The following code example uses Perl/CGI code to output a hidden HTML form field using a dynamic variable:
print "<input type=hidden name=customer_fname value='$cust_first_name'>";
Other languages will have different statements and syntax for data output, such as print or echo statements in PHP. Link code can be output in a similar fashion to the HTML form code above, replacing any number of static variable values with dynamic variables. Please refer any questions you have concerning this type of code to a qualified programmer.
Approval and Denial Posts
When a transaction is approved or denied, data will be sent to the Approval or Denial URL, respectively. The data sent will include everything passed into the signup form through Background Post along with the data entered into the payment form by the consumer, excluding payment information. This data can be parsed and handled in whichever way the script is coded.
Data can be captured in multiple ways depending on the language in which the Approval or Denial script is written. For example:
- Using PHP, the line
$fname = $_POST%22customer_fname%22will capture the consumer’s first name and assign it to a variable called$fname. The variable$fnamecan be named anything you choose. - Using Perl/CGI, the line
<strong>$fname = param("customer_fname")__</strong>will capture the consumer’s first name and assign it to a variable called<strong>$fname</strong>. The variable<strong>$fname</strong>can be named anything you choose.
Other languages will have appropriate functions to capture POST data. A full list of CCBill variables is available later in this document. Note that variable names must be entered exactly as they appear in this document.
Once the script captures these variable values, the script can handle the data in any manner specified in the script, such as inputting the information into a database.
The image illustrates the process of sending and receiving data using Approval and Denial URLs:
Variables
Background Post contains a set of specified system variables that can be used to pull data from CCBill’s system. Two variable sets are used, one for each of the following situations:
- Signup Form. These variables are used to pre-fill the signup form. Naming the variables correctly, as listed below, will ensure the data properly stored in CCBill’s system as the variables are intended.
- Postback. These variables are sent to the Approval or Denial Post URLs, depending on the outcome of the transaction.
In both cases, custom variables will be sent exactly as they were entered.
System variable names must be entered exactly as they appear in this list.
Signup Form
The following chart lists each variable that can be pre-filled in the signup form:
| Variable Name | Description |
|---|---|
| customer_fname | Consumer first name |
| customer_lname | Consumer last name |
| address1 | Consumer address |
| Consumer email address | |
| city | Consumer city |
| state | Consumer state |
| zipcode | Consumer Zip Code |
| country | Consumer country |
| phone_number | Consumer phone number |
| username | Consumer username |
| password | Consumer password |
| lifeTimeSubscription |
The following variables can also be passed into the signup form, but are not shown on the form:
| Variable Name | Description | Example Value |
|---|---|---|
| ccbill_referer | CCBill affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms. | 1626321 |
| formName | Three or more character code identifying the form. | 13cc |
| confirm_password | Confirm password on signup form. | 0 or 1 (yes or no) |
| subscriptionTypeId | Subscription Type ID. | 0108191202000001259 |
| allowedTypes | The subscription options that will appear on the form; this value is generated automatically in the Admin. | 0000003761:840,0000004607:840 |
Postback
The variables listed below are posted back to the Approval or Denial Post URLs:
| Variable Name | Description | Data Type (Max Length) | Example Value |
|---|---|---|---|
| accountingAmount | Actual payout price in USD that the merchant will receive from the purchase. | decimal(9,2) | 14.83 |
| address1 | Consumer address. | varchar(30) | 123 Main Street |
| affiliate | Non-custom referrer for legacy transaction; non-CCBill accounts (EC Suite, etc…) | string | 1234567 |
| affiliate_id | Program Participation Identification. | string | 3542 |
| affiliate_system | -1– Unavailable, retrieve from DataLink 1 – CCBill 2 – WMS Affiliate 3 – Miscellaneous 4 – WMS Tracker | numeric | -1 |
| allowedTypes | Value used to determine pricing options on the signup form. | N/A (no limit) | |
| baseCurrency | Currency in which the price was configured. | int(3) | 840 |
| cardType | Type of credit card used. | string | VISA or MASTERCARD |
| ccbill_referer | CCBill affiliate ID number. This value is passed as 'reseller' when using Traffic Manager to cascade to Epoch forms. | string | 1626321 |
| city | Consumer city. | varchar(30) | Anytown |
| clientAccnum | CCBill merchant main account number. | mediumint(6) unsigned | 900100 |
| clientDrivenSettlement | Reflects whether or not the transaction was pre-approved using Merchant-Driven Settlement. | boolean | 1 or 0 (yes or no, respectively) |
| clientSubacc | CCBill client subaccount Number. | smallint(4) unsigned zerofill | 0000 |
| consumerUniqueId | Unique consumer ID number. | bigint(20) | unsigned |
| country | Consumer country. | varchar(30) | US |
| currencyCode | Three-digit currency in which the consumer was billed. | int(3) | 978 |
| customer_fname | Consumer first name. | varchar(20) | John |
| customer_lname | Consumer last name. | varchar(30) | Smith |
| denialId | The number that identifies a consumer’s declined transaction. NOTE: This number is only provided with declines and is blank with approvals. | bigint(20) unsigned | 111140501000005157 |
| Consumer Email address. | varchar(40) | user@example.com | |
| formName | Three or more character code for the form. | char(255) | 13cc |
| initialFormattedPrice | Initial price with HTML entity for the currency symbol. | string | $10.00 |
| initialPeriod | The initial period of the subscription (in days). | smallint(4) unsigned | 7 |
| initialPrice | The initial price of the subscription. | decimal(9,2) | 4.99 |
| ip_address | Consumer IP address. | varchar(31) | 192.168.27.4 |
| lifeTimeSubscription | Indicates if the transaction is a Lifetime Subscription. Is not posted if not positive. | int | 1 |
| password | Consumer password. | varchar(30) | mYPaSSw0rD |
| paymentAccount | Hash digest of consumer billing information. | string(32) | e1w4858fgb34e5ab2b0e8bd94cb09565 |
| phone_number | Consumer phone number; appears as entered by consumer. | varchar(20) | (123) 456-7890 |
| price | HTML-formatted product price as shown on the form. | string | &36;5.95 for 30 days (non-recurring) |
| productDesc | Product description. | varchar(50) | |
| reasonForDecline | The decline reason (Denial Post URL only). Text description of reasonForDeclineCode. See “Postback Decline Codes” section below for a full list of codes. | string | Subscription ID Provided is invalid (Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.) |
| reasonForDeclineBeforeOverride | The decline reason error that appears when a transaction was declined and later approved using Web Verify. | String | Transaction requires additional approval: please refer to your confirmation e-mail for further instructions. (Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.) |
| reasonForDeclineCode | Numeric decline code (Denial Post URL only). | string | 16 (Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.) |
| reasonForDeclineCodeBeforeOverride | The decline reason error code that appears when a transaction was declined and later approved using Web Verify. | 45 (Please refer to the Postback Decline Codes section at the end of this document for a full list of decline codes and their reason descriptions.) | |
| rebills | The total number of rebills. A value of ‘99’ will rebill indefinitely. | tinyint(2) unsigned | 12 |
| recurringFormattedPrice | Recurring price with HTML entity for the currency symbol. | string | $19.95 |
| recurringPeriod | The period of the subscription (recurring, in days). | smallint(4) unsigned | 30 |
| recurringPrice | The price of the subscription (recurring). | decimal(7,2) | 19.99 |
| referer | Non - CCBill affiliate ID number. This variable is mainly utilized by third party systems. | varchar(16) | 1626321 |
| referringUrl | URL from which the transaction was referred. | string | http://www.example.com |
| reservationId | Consumer’s subscription Reservation ID number. | bigint(20) unsigned | 0109072310330002423 |
| responseDigest | Hash digest of a Dynamic Pricing response. If not using Dynamic Pricing, this value will return as a blank string. | string(32) | s4f5198jgd21a4pk1p2s7sd23lm58937 |
| start_date | Subscription start date. | date | 2008-08-05 15:18:17 |
| state | Consumer state. | varchar(20) | AZ |
| subscription_id | Subscription ID Number (Approval Post URL only). | bigint(20)unsigned | 1000000000 |
| typeId | Subscription Type ID number identifying the price point used in the transaction. | int(10) | 0000060748 |
| username | Consumer username. | varchar(16) | username1 |
| zipcode | Consumer Zip Code. | varchar(10) | 85251 |
Other CCBill services, when used, will return additional variables using Background Post. For more information on the variables returned, please consult the User’s Guide for that service.
Postback Decline Codes
The following table lists potential values for the reasonForDeclineCode parameter and their related reasonForDecline text responses.
| reasonForDeclineCode | reasonForDecline |
|---|---|
| 1 | Website is not available for signup |
| 2 | Unable to determine website signup requirements |
| 3 | Your card type is not accepted, please try another type of credit card |
| 4 | Banking system error |
| 5 | The credit card you entered is not valid |
| 6 | Please check to ensure you entered your expiration dateUsed to show individual corresponding yearly, monthly or daily dates for report data. The date function's format is year-month-day; for example, 2002-01-01. |
| 7 | Please check to ensure you entered your bank account number correctly |
| 8 | Please check to ensure you entered your bank's routing number correctly |
| 9 | Banking system error, please try again |
| 10 | Website has invalid pricing |
| 11 | Transaction declined |
| 12 | You currently have a subscription and are unable to signup |
| 13 | You have already had a free trial |
| 14 | You must enter your CVV2 number on the back of your card |
| 15 | Your account is currently being processed, please check the website you are joining to see if you have access. If not, please contact support@ccbill.com |
| 16 | Subscription ID provided is invalid |
| 17 | Subscription ID does not exist in system |
| 18 | Previous transaction attempt in request was declined |
| 19 | You are not authorized to signup with the provided credentials |
| 20 | No decline |
| 21 | You have already had a trial, please select a normal recurring membership option |
| 22 | Error contacting bank, please try again later |
| 23 | Invalid credit card provided |
| 24 | Transaction denied by bank |
| 25 | Bank error |
| 26 | Card processing setup incorrect for Merchant |
| 27 | System error, please try again |
| 28 | We are unable to process your transaction at this time. Please try again at a later time |
| 29 | Card expired |
| 30 | We are unable to bill the telephone number provided for this transaction. Please return to the website and choose an alternate payment method |
| 31 | Insufficient funds |
| 32 | You must provide CVV2 to complete transaction |
| 33 | Unable to determine transaction type |
| 34 | Error contacting bank, please try again later |
| 35 | Card declined at Pre-Auth SC |
| 36 | Unable to contact bank |
| 37 | We currently do not process for your banks bin |
| 38 | Transaction refused by issuing bank |
| 39 | You have submitted too many times today |
| 40 | The card you are using is not accepted by this Merchant |
| 41 | Merchant inactive |
| 42 | Incorrect address provided |
| 43 | We are unable to process your telephone billing transaction because your provider only allows for one charge, per telephone number, per day, and our records show that you have an existing daily charge to this telephone number. Please return to the website and choose an alternative payment method |
| 44 | We're sorry, at this time prepaid cards are not allowed. Please try a different card type |
| 45 | Transaction requires additional approval: please refer to your confirmation e-mail for further instructions |
| 46 | Transaction declined |
| 47 | Your transaction limit has been exceeded |
| 48 | Your purchase limit has been reached |
| 49 | Unable to authenticate your payment method. Please choose a different payment method and try again. If you need more information, please see 3DS Consumer Authentication FAQs |
| 50 | Email address exceeds ACH transaction throttle |
| 51 | Processor not supported by CDS |
| 52 | TGS transaction has already been captured |
| 53 | Exceeds refund limit |
| 54 | Transaction has already been voided |
| 55 | Transaction has already been refunded |
| 56 | Invalid credit card |
| 57 | Initial Price exceeds maximum |
| 58 | Initial Price below minimum |
| 59 | Recurring Price exceeds maximum |
| 60 | Recurring Price below minimum |
| 61 | System error while creating store credit card |
| 62 | Payment Account Exceeds Transaction Number Throttle |
| 63 | Payment Account Exceeds Transaction Amount Throttle |
| 64 | 3DS authentication failed |
Background Post IP Ranges
| You will receive Background Posts from the following CCBill IP ranges: |
|---|
| 64.38.240.0/24 |
| 64.38.241.0/24 |
| 64.38.212.0/24 |
| 64.38.215.0/24 |
You can use this information to setup firewall rules or confirm the validity of an IP from within your application.
WordPress and iThemes Security Plugin
If you use these features on a WordPress installation and iThemes Security plugin, you may encounter issues receiving posts from CCBill.
Follow these steps to resolve the issue:
- Log into the WordPress website.
- Click on Security Settings.
- Click on Banned Users.
- Uncheck the Enable HackRepair.com's blacklist feature.
Resending Failed Posts
The Background Post system automatically resends unsuccessful posts up to 30 times over the course of a few hours. If you do not receive posts we have no way to resend them to you beyond that.
If you are experiencing many failed posts, check to make sure that you are not experiencing a connection issue like trouble with your hosting company, among other things. Then contact Merchant Support and we will do what we can to help you find a solution.