Introduction

This document is provided as a technical resource to EC Suite clients. It discusses the features and implementation of the EC Suite Background Post system. This document is intended to be read by programmers, technicians, and others with advanced coding skills.

Overview

EC Suite Background Post is a method of passing data between the client’s system and EC Suite’s system. Background Post essentially serves two purposes:

• Pass consumer data into the EC Suite 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 EC Suite 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 EC Suite and process it according to the coding of the script. Approval and Denial Post URLs are coded by the client 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 EC Suite help file.

These two applications of the Background Post system are mutually exclusive and neither is required to use the other.

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 EC Suite Admin. (For more information on how to generate this code, please consult the EC Suite 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 EC Suite signup form while passing in the two custom variables:



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.ecsuite.com/jpost/signup.cgi?clientAccnum=900000&
clientSubacc=0001&formName=11wc&language=English&
allowedTypes=0000003761:840,0000004607:840,0000060248:840,0000063750:840,00000
60752:840&subscriptionTypeId=0000004657:840&customVarName1=customVarValue1&
customVarName2=customVarValue2

Both methods serve the same purpose and either can be used (see Figure 1).



Information can also be passed to the EC Suite signup form using dynamic variables in a custom script. A custom HTML form can call the script, which then sends the variables to the EC Suite signup form. The data flows in a path shown in Figure 2:



The form you create will pass data entered by the consumer to the next form, which will then pass the variables to the EC Suite 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 (shown in boldface):


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 EC Suite 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:



The next section discusses the variables accepted by EC Suite’s system.

Variables

Background Post contains a set of specified system variables that can be used to pull data from EC Suite’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 EC Suite’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

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

Variable Name	Description	Example Value
referer	EC Suite 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 client 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-EC Suite accounts (EC Suite, etc…)	string	1234567
affiliate_id	Program Participation Identification	string	3542
affiliate_system	-1 – Unavailable, retrieve from DataLink 1 – EC Suite 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)	N/A
baseCurrency	Currency in which the price was configured.	int(3)	840
cardType	Type of credit card used.	string	VISA or MASTERCARD
ecsuite_referer	Same as ‘referer’ below. ‘ecsuite_referer’ is used for legacy purposes only; ‘referer’ should be used instead.	string	1626321
city	Consumer city.	varchar(30)	Anytown
clientAccnum	EC Suite client main account number.	mediumint(6) unsigned	900100
clientDrivenSettlement	Reflects whether or not the transaction was pre-approved using Client-Driven Settlement.	boolean	1 or 0 (yes or no, respectively)
clientSubacc	EC Suite client subaccount Number.	smallint(4) unsigned zerofill	0000
consumerUniqueId	Unique consumer ID number.	bigint(20) unsigned	N/A
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 only posted if 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)	Product Description.
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.	string	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’ rebills 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	EC Suite affiliate ID number. This value is passed as ‘reseller’ when using Traffic Manager to cascade to Epoch forms.	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 EC Suite 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 ecsuite.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 Client
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 Client
41	Client 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.