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.

CCBill flow for passing variables


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:

CCBill signup form flow when using dynamic variables in a custom script


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%22 will capture the consumer’s first name and assign it to a variable called $fname. The variable $fname can be named anything you choose.
  • Using Perl/CGI, the line $fname = param("customer_fname")__ will capture the consumer’s first name and assign it to a variable called $fname. The variable $fname 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:

The flow for 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 NameDescription
customer_fnameConsumer first name
customer_lnameConsumer last name
address1Consumer address
emailConsumer email address
cityConsumer city
stateConsumer state
zipcodeConsumer Zip Code
countryConsumer country
phone_numberConsumer phone number
usernameConsumer username
passwordConsumer password
lifeTimeSubscription

The following variables can also be passed into the signup form, but are not shown on the form:

Variable NameDescriptionExample Value
ccbill_refererCCBill affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms.1626321
formNameThree or more character code identifying the form.13cc
confirm_passwordConfirm password on signup form.0 or 1 (yes or no)
subscriptionTypeIdSubscription Type ID.0108191202000001259
allowedTypesThe 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 NameDescriptionData Type (Max Length)Example Value
accountingAmountActual payout price in USD that the merchant will receive from the purchase.decimal(9,2)14.83
address1Consumer address.varchar(30)123 Main Street
affiliateNon-custom referrer for legacy transaction; non-CCBill accounts (EC Suite, etc…)string1234567
affiliate_idProgram Participation Identification.string3542
affiliate_system-1– Unavailable, retrieve from DataLink
1 – CCBill
2 – WMS Affiliate
3 – Miscellaneous
4 – WMS Tracker
numeric-1
allowedTypesValue used to determine pricing options on the signup form.N/A (no limit)
baseCurrencyCurrency in which the price was configured.int(3)840
cardTypeType of credit card used.stringVISA or MASTERCARD
ccbill_refererCCBill affiliate ID number. This value is passed as 'reseller' when using Traffic Manager to cascade to Epoch forms.string1626321
cityConsumer city.varchar(30)Anytown
clientAccnumCCBill merchant main account number.mediumint(6) unsigned900100
clientDrivenSettlementReflects whether or not the transaction was pre-approved using Merchant-Driven Settlement.boolean1 or 0 (yes or no, respectively)
clientSubaccCCBill client subaccount Number.smallint(4) unsigned zerofill0000
consumerUniqueIdUnique consumer ID number.bigint(20)unsigned
countryConsumer country.varchar(30)US
currencyCodeThree-digit currency in which the consumer was billed.int(3)978
customer_fnameConsumer first name.varchar(20)John
customer_lnameConsumer last name.varchar(30)Smith
denialIdThe number that identifies a consumer’s declined transaction.
NOTE: This number is only provided with declines and is blank with approvals.
bigint(20) unsigned111140501000005157
emailConsumer Email address.varchar(40)user@example.com
formNameThree or more character code for the form.char(255)13cc
initialFormattedPriceInitial price with HTML entity for the currency symbol.string$10.00
initialPeriodThe initial period of the subscription (in days).smallint(4) unsigned7
initialPriceThe initial price of the subscription.decimal(9,2)4.99
ip_addressConsumer IP address.varchar(31)192.168.27.4
lifeTimeSubscriptionIndicates if the transaction is a Lifetime Subscription.
Is not posted if not positive.
int1
passwordConsumer password.varchar(30)mYPaSSw0rD
paymentAccountHash digest of consumer billing information.string(32)e1w4858fgb34e5ab2b0e8bd94cb09565
phone_numberConsumer phone number; appears as entered by consumer.varchar(20)(123) 456-7890
priceHTML-formatted product price as shown on the form.string&36;5.95 for 30 days (non-recurring)
productDescProduct description.varchar(50)
reasonForDeclineThe decline reason (Denial Post URL only). Text description of reasonForDeclineCode.
See “Postback Decline Codes” section below for a full list of codes.
stringSubscription 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.)
reasonForDeclineBeforeOverrideThe decline reason error that appears when a transaction was declined and later approved using Web Verify.StringTransaction 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.)
reasonForDeclineCodeNumeric decline code (Denial Post URL only).string16
(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.)
reasonForDeclineCodeBeforeOverrideThe 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.)
rebillsThe total number of rebills.
A value of ‘99’ will rebill indefinitely.
tinyint(2) unsigned12
recurringFormattedPriceRecurring price with HTML entity for the currency symbol.string$19.95
recurringPeriodThe period of the subscription (recurring, in days).smallint(4) unsigned30
recurringPriceThe price of the subscription (recurring).decimal(7,2)19.99
refererNon - CCBill affiliate ID number. This variable is mainly utilized by third party systems.varchar(16)1626321
referringUrlURL from which the transaction was referred.stringhttp://www.example.com
reservationIdConsumer’s subscription Reservation ID number.bigint(20) unsigned0109072310330002423
responseDigestHash digest of a Dynamic Pricing response. If not using Dynamic Pricing, this value will return as a blank string.string(32)s4f5198jgd21a4pk1p2s7sd23lm58937
start_dateSubscription start date.date2008-08-05 15:18:17
stateConsumer state.varchar(20)AZ
subscription_idSubscription ID Number (Approval Post URL only).bigint(20)unsigned1000000000
typeIdSubscription Type ID number identifying the price point used in the transaction.int(10)0000060748
usernameConsumer username.varchar(16)username1
zipcodeConsumer 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.

reasonForDeclineCodereasonForDecline
1Website is not available for signup
2Unable to determine website signup requirements
3Your card type is not accepted, please try another type of credit card
4Banking system error
5The credit card you entered is not valid
6Please 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.
7Please check to ensure you entered your bank account number correctly
8Please check to ensure you entered your bank's routing number correctly
9Banking system error, please try again
10Website has invalid pricing
11Transaction declined
12You currently have a subscription and are unable to signup
13You have already had a free trial
14You must enter your CVV2 number on the back of your card
15Your 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
16Subscription ID provided is invalid
17Subscription ID does not exist in system
18Previous transaction attempt in request was declined
19You are not authorized to signup with the provided credentials
20No decline
21You have already had a trial, please select a normal recurring membership option
22Error contacting bank, please try again later
23Invalid credit card provided
24Transaction denied by bank
25Bank error
26Card processing setup incorrect for Merchant
27System error, please try again
28We are unable to process your transaction at this time. Please try again at a later time
29Card expired
30We are unable to bill the telephone number provided for this transaction. Please return to the website and choose an alternate payment method
31Insufficient funds
32You must provide CVV2 to complete transaction
33Unable to determine transaction type
34Error contacting bank, please try again later
35Card declined at Pre-Auth SC
36Unable to contact bank
37We currently do not process for your banks bin
38Transaction refused by issuing bank
39You have submitted too many times today
40The card you are using is not accepted by this Merchant
41Merchant inactive
42Incorrect address provided
43We 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
44We're sorry, at this time prepaid cards are not allowed. Please try a different card type
45Transaction requires additional approval: please refer to your confirmation e-mail for further instructions
46Transaction declined
47Your transaction limit has been exceeded
48Your purchase limit has been reached
49Unable to authenticate your payment method. Please choose a different payment method and try again. If you need more information, please see 3DS Consumer Authentication
50Email address exceeds ACH transaction throttle
51Processor not supported by CDS
52TGS transaction has already been captured
53Exceeds refund limit
54Transaction has already been voided
55Transaction has already been refunded
56Invalid credit card
57Initial Price exceeds maximum
58Initial Price below minimum
59Recurring Price exceeds maximum
60Recurring Price below minimum
61System error while creating store credit card
62Payment Account Exceeds Transaction Number Throttle
63Payment Account Exceeds Transaction Amount Throttle
643DS 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:

  1. Log into the WordPress website.
  2. Click on Security Settings.
  3. Click on Banned Users.
  4. 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.