Table of contents


1. Overview

This document describes 4 different methods by which an affiliate can post data (leads)to the TCH leads database. It's up to you which method you choose but each method requires a different degree of technical ability to integrate into your website. Whichever route you take, you may be able to get technical support via the affiliate-marketing-school.com forum should you run into trouble. However, our goal is to provide affiliates at all technical levels with a method that falls within the realm of their capabilities. Therefore we offer the following guideline as to which method might suit which type of user:

Non-technical user: Use our iframes on your existing site.

Intermediate user: Integrate the standard, customizable forms into your exisiting site and change them as you wish.

Technically advanced user: Use the SOAP API to allow your existing site to post leads directly to the service.

User with existing http-post framework: Post XML formatted leads to our XML/HTTP server using your company's existing http post technology.

In order to post data, the first thing you'll need is a test account in the TCH student test database*. You can register a new account here.

*Please note that even if you have had a site approved and have registered an account in our Leads Database with an approval code, this does not create an account in the student test database. In order to test your site, you must also manually create a test account by clicking the link above.


2. Using iframes

The easiest way to send your lead data to TCH is by using our iframe code. This method allows you to place forms on your site which are pre-coded to send data directly to TCH.

There are 3 simple steps to using an iframe on your website

  1. Login to TCH
  2. Use the iframe generator to design your iframe
  3. Copy and paste the iframe code into your site

2.i. Login to TCH :

In order to generate iframe code which uniquely identifies you as the seller, you first need to login to your TCH account. Since the TCH database sends leads directly to merchants, we ask you not to use the live database for practise and testing. Until you are certain that everything is working as you wish, you should login to the Student Test Database and get your iframe code from there. While you test, you can login to the Student Test Database and check your leads in exactly the same way you do with the live db to verify that everything is working. Only when you're ready to publish your site to the public and allow genuine applications to be received should you switch to the live db. This can be done either by editing a tiny portion of the existing iframe code or by regenerating the iframe code in the live db.

Once logged into TCH, click the "User Profile" link on the left. Then click on the link to "Generate iframe code'.

2.ii. The iframe generator

The only necessary step for generating your iframe code is to select which type of leads you'll be collecting, using the "Form type" dropdown. Clicking on the "Generate iframe code" button will then create the iframe code to insert into your webpage. Everything else in the iframe generator is optional.

Having selected the type of form you'll be working with, the other options enable you to customize the appearance of the form to match the design of your site and also to link back to tracking code and thank-you pages within your own site.

Whenever you click "Generate iframe code", you can scroll beneath the box containing the iframe code to see a preview of how the form will look. Let's examine the available options:

  • Submit As
    • Lets you specify whether your iframe will only send leads to CPA or Back-End merchants. Leave this set to "Auto" if you want the choice to be made automatically for you (which will avoid the possibility of leads going unsold when no merchants of the type selected are available). You can read more about this option here.
  • Form background
    • This has been set by default to "transparent" which works well on most sites; allowing your site's page background colour to carry through the form. If you wish, you can click the colour picker to the left of the textbox and specify a different background colour.
  • Text colour
    • This applies to all text used throughout the form; both for labels and for field data entered by the user. Default is black.
  • Field color
    • This attribute allows you to set a different background colour for the fields (where the user is required to enter data). Default is white.
  • Position
    • The horizontal position of the form on your page. Please note that, for aesthetic purposes, this is ignored in the form preview but will have the expected effect when the iframe code is used in your webpage.
  • Font size
    • Set to 80% by default, this attribute sets the size of all text in the form and consequently affects the overall size of the form itself.
  • Failed - Thank-you page url*
    • This allows you to redirect visitors to your own custom thank-you page when a submission is unsuccessful (see thank-you pages with iframes and forms for a full explanation). Please note that when using iframes, the thank-you message is displayed in a table with a width setting of 300 (so it displays cleanly within the frame). Keep this in mind if you decide to use a custom thank-you page.
  • Success - tracking code page url*
    • This will allow you to run PPC tracking code on the auto-generated thank-you page by providing a link to a simple html page, the body text of which will appear as a footnote. A sample html page can be found here. Either by using the provided sample or by creating your own simple page, paste your PPC tracking code into this page and upload it somewhere on your website. Then simply enter the url of this page into the Success - tracking code page url box in the iframe generator. When a submission is successful, the simple text in this page will be displayed at the bottom of the thank-you page and your tracking codes will be run

* All urls entered in the iframe generator page must be full-length. For example, it is not enough to simply enter thank-you.html. You must enter the full path, eg. http://www.mysite.com/mydirectory/thank-you.html.

2.iii. Copying and pasting iframe code

Once you've generated the necessary iframe code, it can be copied and pasted into the body of your html page. With most html editors, this is as simple as placing the cursor where want the form to appear, switching to code view or html view and then pasting in the iframe code. When copying the code from TCH, make sure you select the entire code block first (the easiest way is right-click>select all). Your copied code should begin with <iframe> and end with </iframe>

2.iv. Changing iframe code from testing to the live db

If you've created a test-page using iframe code from the Student Test db, you can switch your site to live lead delivery by simply replacing your existing iframe code with new code from the iframe generator in the live db*.

Alternatively, if you've made some edits to your iframe code block and prefer not to replace the entire thing, you can switch to live service by making three small edits in the first line of your iframe code, inserting new values from the live db's* iframe generator. Simply change test. to www. at the beginning, then change Studentdb to Leadsdb in the url (case-sensitive) and finally change the value of tchid= to the new value shown in the live db's* iframe code. The example below shows where these edits should be made:

Testing:

<iframe src="http://test.traffic-clearing-house.com/Studentdb/direct_api/iframes/short-secured-form.php?tchid=74963e174b76ttt112f38e4133dab5a2&bgcolor=&textcolor=666600&formcolor=transparent&fontsize=80&subtype=CPA"

Live:

<iframe src="http://www.traffic-clearing-house.com/Leadsdb/direct_api/iframes/short-secured-form.php?tchid=2616j664b01cab116a29e7773dfr7t0&bgcolor=&textcolor=666600&formcolor=transparent&fontsize=80&subtype=CPA"

* For access to the live db, your site must be approved by an admin. If you have not yet had your site approved you can do so by clicking here.

2.v. Checking to make sure your iframe is working

Once you have a live iframe on your site you can test it by clicking submit on an empty form. If all is working, you should get a validation error (e.g. Forename cannot be empty). If you get an unauthorized user fault, your iframe code is not working. If you've edited the values by hand, go back and check that you haven't missed off a part of the tchid, removed the = sign or some other simple textual error (missing slashes in the url and not observing the case-sensitivity of the url are also common errors). As a further test, try replacing the entire iframe code block and see if this solves the problem. If the problem persists, please post a message in Tech Support and we'll try to help you from there.


3. About thank-you pages and emails

When you use the standard forms or iframes, all thank-you pages are generated automatically by TCH. When a lead is successfully submitted, the customer will see a thank-you page which may also include the footer message and tracking code you provided in the iframe generator. The text on this page is not set in the script itself, it's a part of the return packet sent back by our webservice. You will also receive an email confirming that the lead was accepted. This email will include the lead number, the payout and a copy of the lead itself.

When a submission is not successful, two things happen: First, the details of the lead are emailed to you so you can try to find another home for it. While this is happening, the user is shown a thank-you page which, by default contains the following text:

Thank you for your submission.
Your application is now being processed and we will be in contact with you very soon.

Both the iframe and the standard form offer a simple means of replacing this page with something of your own design. In the case of the standard form, you specify the url of your thank-you page in config-tch.php. For iframe users, the iframe generator includes a text box into which you can enter the page url. In the standard form you also have the option to change only the text on this page in config-tch.php. For example, if you don't have anywhere else to send unsuccessful leads and do not plan to contact unsuccesful applicants, it would be more appropriate to change this message to something like 'Thank you for your application. Unfortunately we are not able to assist you at this time'.

Important note for iframe users: The email address to which lead reports are sent is taken from your TCH user profile. Before using your iframe, please make sure that this information is up-to-date.


4. Using forms

Auto-submit form scripts, written in php, can be downloaded from the following links:

Debt Management/IVA
Debt Management Mobile*
Secured Loans
Unsecured Loans
Life Insurance
Life Insurance Mobile*
Private Medical Insurance (PMI)
PMI Mobile*
Logbook Loans*
Logbook Loans Mobile*
Income Protection Insurance*

* NOTE: The newer-style forms (marked with a *) differ from all other forms in that there is only one .php file which contains all the functions normally provided in 8 separate files. All of the configuration options mentioned below still apply. The only difference is that all of these settings can be found at the top of the form file - tchform_xxx.php

Each of the above* zip archives contains 8 files as follows:

  • <formtype>-form.php
  • <formtype>-brain.php
  • <formtype>-field-info.php
  • <formtype>-email.php
  • header.php
  • footer.php
  • thank-you.php
  • config-tch.php

NOTE: All form packages are initially configured to submit leads to the test database. Since the TCH live database sends leads directly to merchants, we ask that you do not use the live database until your forms are tested and known to be working correctly with the test database. While you test, you can login to the Student Test Database and check your leads in exactly the same way you do with the live db to verify that everything is working. Only when you're ready to publish your site to the public and allow genuine applications to be received should you switch to the live db.

There are three necessary steps to begin using these forms on your website:

  1. Download NuSOAP
  2. Edit the configuration file*
  3. Upload the scripts to your site

4.i. Downloading NuSOAP

NuSOAP is a php class library which allows these scripts to talk to the TCH webservice. The latest version of NuSOAP can be downloaded at http://sourceforge.net/projects/nusoap/

The NuSOAP package contains a few different folders but the only one we really need is the folder called "lib". This entire folder should be uploaded to the directory where your form scripts will reside, making sure not to separate the files from the folder.

4.ii. Editing the configuration file

Using any text editor, open the file config-tch.php*, (this file is part of the zip package for whichever form type you downloaded). There are a few options to edit here but only the first three items are imperative for the forms to work. Enter your login data and your email address between the double-quotes as shown below, then save the file:

$tch_username = "bob_test"; //Your TCH username
$tch_password = "1234567"; //Your TCH password
$your_email = "bobtest@mydomain.com"; //The service will send reports to this address

If you wish, you can leave the rest of the file unchanged and proceed to the next step.

4.iii. Other configuration options

Our forms provide the option for you to specify the type of merchant you would like to receive your lead. So, for example, if you wanted have all your submissions go to a CPA merchant (pay-per-lead), you would edit the submit_as setting as follows:

$submit_as = "CPA";

This would mean that, in cases where a CPA merchant was not available, the submission process would terminate and you would receive an email informing you that there were no available merchants meeting your criteria.

The default setting for submit_as is blank which allows our system to automatically route your lead to the best available offer at the time of submission.

To switch lead submission from the test database to the live database*, simply change the value of $target_db thus:

$target_db = "Leadsdb";

Please note that this value is case-sensitive and must begin with a capital letter.

* For access to the live db, your site must be approved by an admin. If you have not yet had your site approved you can do so by clicking here.


For the option $your_thank_you_page_url, please see 'about thank-you pages and emails'. If you don't use a custom thank-you page for unsuccessful applications, you can still personalize the standard thank-you page by editing/supplying the following information:

$your_site_name = "Super Duper Loans UK"; //Name of your website/company
$your_logo_url = "http://www.superduperloans.co.uk/images/logo_small.gif"; //URL to a logo for your site/company
$your_thank_you_text = "Thank you for choosing Super Duper Loans. <br>We'll be in touch with some <i>Super Duper</i> offers very soon.";

If you plan to provide a logo url, you should create a version of your logo which is approximately 200px x 80px at 72 dpi.

The variable $your-thank_you_text can include html formatting tags such as:

  • <br> Page break
  • <b></b> Bold
  • <i></i> Italic

4.iv. Uploading the scripts to your site

Once the config file is edited, use an ftp client to upload all 8 files to the directory of your choice. The NuSOAP library's "lib" directory must also be uploaded to the same directory as these other files.

4.v. Integrating the form with your existing site

The form itself is contained in the file <formtype>-form.php. However, as long as your server is running php, you can easily copy and paste the form code into an existing html or php webpage. Make sure to copy the entire document, from the first <?php tag to the last ?> tag. Also, if the filename of the page you pasted the code into ends with .html or .htm, you should change it to .php

The standard form uses css styles which reside in the file header.php. These styles govern the size and formatting of the form elements as well as the text style, colour etc. When adding the form to an existing webpage, it's likely that the existing page already has it's own styles, either at the top of the page in the <head> section or in a separate stylesheet (usually called something like stylesheet.css). To avoid confusion, it's good practice to move the styles that are in header.php to the place where the page's other styles already reside. Once this has been done, you should be able to delete header.php and find that the form should look the same. (Click here for some css notes on the newer-style forms e.g. Logbook Loans.)

An alternative way to include the form on an existing page is to upload all the form files to your site and then place a simple iframe in the body of your main page which points to the form you want to include. Here's an example using the debt management form:

<iframe src="debt-management-form.php"
name="my_iframe"
width="500"
marginwidth="1"
height="600"
marginheight="1"
align="left"
allowtransparency="true"></iframe>

In this example, the file debt-management-form.php is expected to be in the same directory as the page which contains the iframe. However, we could tell the iframe to look for the form in a different directory:

<iframe src="forms/debt-management-form.php"This would look in the "forms" directory which is below the site's root, whereas;

<iframe src="../forms/debt-management-form.php"..would look in the "forms" directory which is above the site's root.

 

4.vi. Common files (for multiple-form sites)

If you plan to use more than one of these forms on your site, you do not need to upload the entire package for each additional form that you wish to implement. The following files are common to all forms:

  • header.php
  • footer.php
  • thank-you.php
  • config-tch.php
  • /lib (the nusoap class library)

As long as there is one instance of each of these files in your form directory, you do not need to upload them again.

4.vii. Switching from testing to live db

To switch lead submission from the test database to the live database, simply change the value of $target_db in config-tch.php thus:

$target_db = "Leadsdb";

Please note that this value is case-sensitive and must begin with a capital letter.

4.viii. Notes for Wordpress users

Integrating our forms into a Wordpress site is a little more complex. Click here for a detailed guide.


5. Customizing forms

Each of the standard forms offers a few simple options for customization. Obviously, depending on your technical ability it is possible to change every aspect of the form's appearance and behaviour to better suit your own site: However if this is your aim, you would be better advised to integrate the SOAP API into your existing site instead of trying to reverse-engineer the standard forms.

Here are some of the more obvious candidates for customization:

5.i. Changing styles, colours and text

The appearance of the form is governed by the css style elements in the header file - header.php

<style type="text/css">
body,td{font-family:verdana;font-size:80%;color:black;}
.input-text{font-family:verdana;font-size:80%;background-color:white;color:black;width:175px;}
.input-select{font-family:verdana;font-size:80%;background-color:white;color:black;width:175px;}
</style>

The header contains one tag style (body) and two class styles (input-text and input-select) which govern everything that appears on the form. There's plenty of good documentation online about editing style tags. Our intention here is simply to let you know where to find them. Please see here for more information about merging our form into sites which have existing styles.

Note: If you are using the newer single-page forms (eg. Logbook Loans or Debt Management mobile), these css elements can be found in the <head> section of the form file. If you are merging this form into an existing site with it's own <head> or separate css stylesheet, the best practise is to completely remove the <style> ... </style> block from the tch form and instead add the css styles from this file to your site's <head> or stylesheet.

5.ii. Changing the thank-you page

The source for the auto-generated thank-you page is in the file thank-you.php. This file outputs a very simple html page which displays a message to the applicant after the lead has been submitted.

While we have provided a means of redirecting unsuccessful applicants to a thank-you page of your choosing, no such option is available for successful applications. If you want to create a customized thank-you page for your site, the best method is to edit the html portion of thank-you.php:

<center>
<table width="600">
<tr>
<td><?php echo $merchant_name?></td>
</tr>
<?php if(!empty($merchant_logo_url)){?>
<tr>
<td><IMG SRC="<?php echo $merchant_logo_url?>" BORDER="0" ALT=""></td>
</tr>
<?php } ?>
<tr>
<td><?php echo $merchant_thank_you_text?></td>
</tr>
</table>
</center>

You can freely paste any html code you like into this area. This is also the area into which you would paste any tracking codes/scripts provided by PPC engines like Google, YSM etc. (just paste them right after the </center> tag at the end).

Note: If you are using the newer single-page forms (eg. Logbook Loans or Debt management mobile), there are two varables at the top of the form - $success_thank_you_page_url and $failed_thank_you_page_url which allow you to specify your own thank-you page in the event of either a successful or a failed submission. If you are not using your own thank-you pages and simply wish to add additional coding in the event of success or failure (for example, PPC tracking codes) this code can be added directly above the lines which read:

// ***************************************************Unsuccesful application ends here

// ***************************************************Successful application ends here

5.iii. Tracking keywords and other variables through your form

Sometimes it may be useful to pass values from your PPC campaign to your form and then include these values in the email which the system sends you. This is particularly useful for passing along the keyword which successfully led the customer to your ad. To accomplish this, you simply need to add a small amount of extra code to two of the form files - <formtype>-form.php and <formtype>-email.php.

For all of these examples, the name of the file to edit will depend on which type of form you're using. For example if you're using a pmi form, <formtype>-email.php will refer to the file called pmi-email.php whereas if you're using a life insurance form it will refer to life-insurance-email.php.

All of the examples below assume that you have appended a new variable called "keyword" to your PPC ad's url, thus:

http://www.yoursite.com/short-secured-form.php?keyword=Consolidation If you're using Google AdWords, there's a shorthand method you can use to have Google automatically insert the keyword which led to your ad being displayed:

http://www.yoursite.com/short-secured-form.php?keyword={keyword}


So once that's done, here are the changes you need to make to the form scripts in order to pass this keyword. First, in <formtype>-form.php, find this line:
<input type="hidden" name="IPAddress" value="<?php echo $_SERVER['REMOTE_ADDR'];?>">

After this line, insert a new line and paste the following: <input type="hidden" name="keyword" value="<?php echo $keyword;?>">

Save and upload the file back to your server.

Now open <formtype>-email.php and find this:
</tr>
</table>

After the </tr> and before the </table>, insert a new line and paste the following:
<tr>
   <td>Keyword</td>
   <td align="right">$keyword</td>
</tr>

Save and upload the file back to your server.

The above procedure can be used to pass any variable through your form by simply including it's value in the url which leads a visitor to your site. For example, if you wanted to also include a variable called "ppcsource" to indicate which PPC engine the lead came from, you would first append it to the url like this:

http://www.yoursite.com/short-secured-form.php?keyword=Consolidation&ppcsource=Google

Then you would add this to <formtype>-form.php <input type="hidden" name="ppcsource" value="<?php echo $ppcsource;?>">

..and this to <formtype>-email.php
<tr>
   <td>PPC Source</td>
   <td align="right">$ppcsource</td>
</tr>

Using this same method, you can pass as many variables through your form as you wish. For each additional variable, you just need to append one more instance of &variablename=variablevalue to the end of the source url.

Note: If you are using the newer single-page forms (eg. Logbook Loans or Debt Management mobile), there is no need to change anything in the email function. You will however need to add the name of each new hidden field to the validation exclusions list. For example, if you've created a new hidden field called "keyword". First find this line:

$validation_exclusions = array('makeSelected', 'post_data');..then add your new field to the array of fields to be excluded

$validation_exclusions = array('makeSelected', 'post_data', 'keyword');


 

6. Manual integration using SOAP

For those familiar with SOAP webservices, a WSDL file is available for reference.

The WSDL for the live tch webservice can be found here:
https://secure.traffic-clearing-house.com/Leadsdb/direct_api/TCH_Exchange.php?wsdl

However, until your scripts are fully tested, please use the test environment:
http://test.traffic-clearing-house.com/Studentdb/direct_api/TCH_Exchange.php?wsdl

If you're not familiar with the WSDL protocol, feel free to ignore the above*. Using the API is as easy as pasting some of our code examples into a php script, editing a few configuration items and uploading to your server. The biggest part of the job is replacing the sample field data with the actual data from your form and writing the necessary code to handle any error and validation messages which may be returned from the service.

* The WSDL files will still be useful to you when it comes to creating select box/dropdown options in your form - all the valid options for each field are listed in the WSDL file.You may also use our iframes as a reference for your form design form since the iframe fields are always up-to-date.

6.i. Using SOAP with php

In php, there are three popular methods for consuming SOAP webservices

  • PHP5 - integrated SOAP functions
  • NuSOAP
  • Pear::SOAP

In creating and documenting the TCH webservice, we decided on NuSOAP because it can easily be integrated into all popular versions of PHP (not just version 5) and also because NuSOAP requires no installation or editing of config files by a server's administrator (which might cause some headaches for those using remotely hosted sites). While all the php examples given use the NuSOAP syntax, those preferring to use one of the other SOAP packages will find that the script can be adapted by simply changing the names of the main SOAP functions used (which usually means changing just one or two lines of code at most). If in doubt, please ask on the forum and we'll try to help in adapting the scripts.

The latest version of NuSOAP can be downloaded at http://sourceforge.net/projects/nusoap/

6.ii. Submitting a lead

The TCH SOAP webservice offers a number of different functions (also called "methods") to accomplish different tasks. However, the function you'll probably be using the most is app_submit. This function takes an array which includes the fields for your lead along with your TCH username, password and one extra field called "Type" which tells us the type of lead you're submitting to TCH. The question of which specific fields should accompany your login data will depend on the lead type you're submitting. The schema for each different lead type is detailed later in this section.

Below is a sample php client script for submitting a debt management/IVA lead. (Click here for a sample script in .NET)

<?php
// Insert the NuSOAP class library
require_once('nusoap/lib/nusoap.php');   //Path to nuSoap

// Create the client instance
$client = new nusoap_client('http://test.traffic-clearing-house.com/Studentdb/direct_api/TCH_Exchange.php?wsdl', true);

// Check for errors in the constructor
$err = $client->getError();
if ($err) {
// Display the error
echo '<h2>Error</h2><pre>' . $err . '</pre>';
}

//Create proxy
$proxy = $client->getProxy();

//Build the array of values to submit a Debt Management/IVA lead
$login = array(
'TCHuser' => '',   //Your TCH username
'TCHpass' => '',   //Your TCH password
'Type' => 'DML',
'SubmitAs' => 'CPA'     //Options are 'CPA', 'Back-End' or leave it empty to let the db decide for you.
);

$app1 = array(
'Forename' => 'Bob',
'Surname' => 'Smith',
'Email' => 'bsmith56@hotmail.com',
'HomeTel' => '01734555463',
'MobilePhoneNo' => '07765352876',
'ContactTime' => '0900',
'MonthlyIncome' => '3000',
'IPAddress' => '192.165.13.23'   //Must be captured from applicant during submission
);

$app2 = array(

);

$residential = array(
'Address' => '25 Test Street',
'Area' => 'Test acres',
'Town' => 'Testville',
'County' => 'Testshire',
'Postcode' => 'cp65yu',
'ResStatus' => 'Homeowner'
);


$financial = array(
'Expenses' => '2700',
'TotalOwed' => '20000',
'NumDebts' => '4',
'NatureOfIncome' => 'Employed',
);

$lead = array(
'TCHLogin' => $login,
'Applicant1' => $app1,
'Applicant2' => $app2,
'Residential' => $residential,
'Financial' => $financial
);

// Call the SOAP method
$result = $proxy->app_submit($lead);

// Check for a fault
if ($proxy->fault) {
echo '<h2>Fault</h2><pre>';
print_r($result);
echo '</pre>';
} else {
// Check for errors
$err = $proxy->getError();
if ($err) {
// Display the error
echo '<h2>Error</h2><pre>' . $err . '</pre>';
} else {
// Display the result
echo '<h2>Result</h2><pre>';
print_r($result);
echo '</pre>';
}
}

// Display the request and response in the browser
echo '<h2>Request</h2>';
echo '<pre>' . htmlspecialchars($proxy->request, ENT_QUOTES) . '</pre>';
echo '<h2>Response</h2>';
echo '<pre>' . htmlspecialchars($proxy->response, ENT_QUOTES) . '</pre>';
// Display the debug messages
echo '<h2>Debug</h2>';
echo '<pre>' . htmlspecialchars($proxy->debug_str, ENT_QUOTES) . '</pre>';
?>
This sample simply displays the result of the submission in a browser window. To retreive the elements of the response for further processing, you would simply test the value of $result["<element_name>"]. Please see the next section for more detail.

6.iii. Handling the response

After a lead is submitted using app_submit, the service returns an array of the type 'LeadResponse' which will indicate whether the submission was successful or not. A successful submission will return something like this:

Array
(
   [tch_appSuccess] => 1
   [tch_leadNumber] => DML3301
   [tch_payout] => 75.00
   [merchant_txtThankYou] => Thank you. Your lead has been sent to Test DM merchant. We will contact you shortly
   [merchant_type] => CPA
   [tch_autoReject] => 0
)
The value of the element tch_appSuccess is always an integer; 1 for success, 0 for failure. The other elements in the array provide data for your own record keeping along with a thank you message.

So, a conditional to test whether an application was successful and if so, display a thank-you page might look something like this:

if ($result["tch_appSuccess"] == 1){
   header("Location: thankyou.php?");
} else {
   //Take some action if the lead didn't go through correctly
}


An unsuccessful submission will return something like this:

Array
(
   [tch_appSuccess] => 0
   [errorCode] => 1103
   [errorField] => x_C1HomeTel
   [errorType] => TCH local validation error - [x_C1HomeTel]
   [errorMsg] => Invalid Home phone number [(012t77) 372-89] - UK telephone numbers should contain 10 or 11 digits, no other characters allowed
)

The element errorMsg can be echoed back to the user via whichever means you prefer (e.g. A javascript alert box), while the value of errorField can be used to focus the field that needs attention (by passing it to javascript's GetElementByID function, for example).

Another important element of the return array is errorType. There are four error types;

  1. TCH local validation error - [fieldname]
  2. Remote XML error
  3. TCH Duplicate
  4. TCH Merchant status


All messages of the type 'TCH local validation error' have the same structure i.e: the element errorMsg will contain useful information about the nature of the errant data which is designed to be echoed back to your site's visitor. The same can also be true for the second type 'Remote XML error' which, as it's name implies is an error from outside the TCH server; it comes directly from the merchant's webservice. Please see the error list for details of which remote errors should be echoed to your site's visitor.

The last two types, 'TCH Duplicate' and 'TCH Merchant Status', are used to indicate that the lead cannot be accepted for the reason explained in 'errorMsg' . You'll need to decide for yourself what action to take in this event (e.g. Send yourself an email, try sending it to non-school merchant etc.). In both these cases however, it is important to remember that the error message is directed to you, the site's owner and not to your visitor (your visitor would not understand a response such as 'TCH has reached it's daily quota for this lead type').

To assist you in error handling and trapping, we have provided a comprehensive error list in this documentation. In most cases you should be able to trap non-consumer errors by parsing the errorCode element appropriately.

6.iv. Submitting other lead types

The sample scripts focus on submitting a Debt Management/IVA lead. To submit a different type of lead, the only difference is the way you build the field array $lead() which is passed to app_submit. Every other part of the script remains the same. Please click on the following links to see the field array structure for each lead-type.

6.v. Switching from testing to live submission

All of the sample scripts provided will allow you to submit leads to the Student Test Database. While you're testing, you can login to the Student Test Database and check your leads in exactly the same way you do with the live db to verify that everything is working. Only when you're ready to publish your site to the public and allow genuine applications to be received should you switch to the live db. This can be accomplished by simply changing the url in the client constructor:

$client = new nusoap_client('https://secure.traffic-clearing-house.com/Leadsdb/direct_api/TCH_Exchange.php?wsdl', true);

Please remember that the url is case-sensitive and the target db name must begin with a capital letter.

6.vi. Other TCH webservice functions

In addition to lead submission, the TCH SOAP webservice also offers the following functions (click the function name for details and implementation)

merchant_stats

This provides a means of checking the current merchant status, (limits, bids etc.) . It is the programmatical equivalent of checking the merchant status/current bids page when logging into TCH.

is_full_quota

Simple boolean check to determine whether all merchants of the specified type have reached quota.

6.vii. Error List

Click here for a comprehensive list of errors which may be returned from app_submit


 

7. XML/HTTP Server

If your organization has an existing framework which posts lead data via http, you may use our XML/HTTP server to post leads to the service. Please note that this is not a recommended technology for new users wishing to develop forms (the standard forms and SOAP API provide superior performance for new developers). The XML/HTTP server provides an alternative for introducers who encounter difficulty implementing a SOAP client on an existing system.

7.i. Service urls

The live server can be found at:
https://secure.traffic-clearing-house.com/Leadsdb/direct_api/tch_xmlhttp.php

However, until your scripts are fully tested, please use the test environment:
http://test.traffic-clearing-house.com/Studentdb/direct_api/tch_xmlhttp.php

Please note that we do not permit the posting of test leads to the live system.

7.ii. Formatting of lead data

The content of the lead should be formatted into an XML document which is then posted to the appropriate service URL. You can find an example of how to form the XML document for each lead-type by using the following links:

Debt Management (DML)
Debt Management mobile (DMM)
Logbook Loans (LBL)
Logbook Loans Mobile(LBM)
Life Insurance (LIN)
Life Insurance Mobile (LIM)
Private Medical Insurance (PMI)
PMI Mobile (PMM)
Secured Loans(SLS)
Unsecured Loans (SLU)
Income Protection Insurance (IPS)

7.iii. Handling the response

The response to any succesful post will be an XML document with the root node <LeadResponse>. Please see here for an explanation of the different types of responses that may be returned.

7.iv. Important notes for posting

When forming the xml for a post, the document must not include any element which has no children.

For example, the LIN, SLS and SLU lead-types have provision for a co-applicant (called Applicant2 in the XML document). However not all leads will be joint applications. Your form processing software will need to determine whether the lead actually contains the details of a second applicant and, if it does not, you must ensure that the XML document does not contain an <Applicant2> element. The <Applicant2> element should only be included when there is data with which to populate its children. Failure to observe this rule will cause the post to fail.

Back to Top

 

8. Copyright and disclaimer

This documentation, the api package, forms, iframes and SOAP/XML schema are copyright (c) 2008 and thereafter: Traffic Clearing House - All Worldwide Rights Reserved. Content may not be republished, in any manner, without prior written permission.