Loading...
 

Background Post



INTRODUCTION

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>

Please note that customVarName1 and customVarName2 are only example names and can be anything you choose. The values can also be anything you choose.
You may use a text link instead of a button, if desired. 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.

method1.jpg

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:

flow1.jpg

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"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.

  • 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.
Figure 3 illustrates the process of sending and receiving data using Approval and Denial URLs:

url1.jpg

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
email 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
email 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. correctly
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 at 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.

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.

 Note

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.