DotAdmin User Guide
The Callback and Receipt Templates
The final stage in the order process is the Callback process. This page is called by the payment processor after the customer's credit card information has been taken, and can be used to generate receipts for the customer.
There are actually three templates involved in generating receipts. The Callback and Receipt templates are used to format a web page receipt and are covered here, but you may also want to read about the Order Email template, which sends an order confirmation via email to the customer.
The Receipt Template
This template is very basic. It acts as a page template to contain the callback template, and the only placeholder available to it is {content}, which gets replaced with the completed callback template.
There are a couple of reasons for using a special page template here, rather than the “main” template used to contain the output from all other processes: Firstly, the customer may want to print the receipt page, so we might want to make sure the page is no wider than 640 pixels and that it doesn't contain a lot of graphics.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Order Confirmation</title>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1">
</head>
<body>
<table border="0" width="600">
<tr>
<td align="center">
{content}
</td>
</tr>
</table>
</body>
</html>
An example receipt template.
Secondly, some payment processors actually take the results of the callback process and display them at the payment processor's website, and only allow a short amount of time to receive the completed page before they abandon the process and show their own receipt to the customer. Because of this, we may want to make sure the process completes as quickly as possible by removing any navigational elements from the page template or other unnecessary features.
The Callback Template
The Callback Template.
As we already mentioned, the main purpose of the callback template is provide a summary of the customer's order following the payment process. This could mean displaying the cart totals and billing and shipping address details in the case of a successful order, or it could mean displaying a message saying that payment was not taken and the order was not successful.
The first template element in the callback template is the IF {successful} condition. As you might expect, anything within this condition will only be displayed if the order is paid for. An ELSE instruction can be added to display messages relating to unsuccessful orders.
<!-- IF {successful} -->
<h1>Payment Received</h1>
<p><b>Thank you for shopping at {company_name}. </b></p>
<p>Your payment has been received
<!-- IF {lead_time} -->
and your order will be shipped to you within {lead_time}
days
<!-- /IF {lead_time} -->
.</p>
<!-- /IF {successful} -->
<!-- ELSE -->
<h1>Payment Cancelled</h1>
<p>Your transaction has been cancelled.</p>
<!-- /ELSE -->
Providing messages for successful and unsuccessful transactions in the Callback template.
Note: The {lead_time} placeholder in the example above produces a number of days until the order can be fulfilled. This value is the product of the standard shipping turnaround time for the customer's destination, and the longest lead time (if any) for any out-of-stock items in the customer's order.
BLOCK {bad_auth}
This block is used to report the only error that the callback template deals with. If the callback page is requested with parameters that do not constitute a genuine order, this message is displayed to say that the transaction has not been processed.
BLOCK {contacts}
This block repeats back the customer's contact and address details which were collected at the checkout stage. There is another block within this one, named BLOCK {shipping}, which contains the delivery address if a separate delivery address was provided. If there is no delivery address, this block is not used.
<!-- BLOCK {contacts} -->
<table width="600">
<tr>
<td>
<p><b>Billing Contact:</b></p>
<p>{salutation} {f_name} {l_name} <br>
{b_flatno}<br>
{b_street}<br>
{b_town}<br>
{b_state}<br>
{b_destination}<br>
{b_postcode}
</p>
</td>
<!-- BLOCK {shipping} -->
<td>
<p><b>Delivery Address:</b></p>
<p>{s_name}<br>
{s_flatno}<br>
{s_street}<br>
{s_town}<br>
{s_state}<br>
{s_destination}<br>
{s_postcode}</p>
</td>
<!-- /BLOCK {shipping} -->
</tr>
</table>
<!-- /BLOCK {contacts} -->
Displaying contact and address details in the Contacts and Shipping blocks.
Displaying the Shopping Cart
In the callback template, there are two ways to display the contents of the shopping cart. {literal cart} is the easiest way, which will include the normal shopping cart template in the callback template. If you would rather use a different design for the receipt, you can use the relevant template instructions from the cart template and they will work here too. These include: BLOCK {header}, BLOCK {cart_items_locked}, BLOCK {costs} and BLOCK {subs_locked}
You should also include the {cart_id} as a unique reference code for this order, and (if one is returned by your payment provider) {trans_id}, which will contain your unique payment reference ID.
BLOCK {url}
If the customer has bought a subscription to a protected area of the site, or has bought a downloadable product, this block is used to display information specific to that purchase.
IF {download} and IF {subscription} can be used to provide messages appropriate to the purchase. We will also need to display a link to the product, and (if relevant) a message telling the customer how long this link will be valid.
<!-- BLOCK {url} -->
<!-- IF {download} -->
<p>You have been granted access to download: <i>{title}</i>.
<b><a href="{site_address}content/download/?file={path}{ext}
&remember=remember">Click here to begin your download</a></b>.
</p>
<!-- /IF {download} -->
<!-- IF {download_ttl} -->
<p>This link will remain active for {download_ttl} days.</p>
<!-- /IF {download_ttl} -->
<!-- IF {subscription} -->
<p>Thank you for subscribing to <i>'{title}'</i>.
<b><a href="{site_address}content/{path}{ext}
&remember=remember">Click here to log in to {title}</a></b></p>
<!-- /IF {subscription} -->
<!-- IF {subs_ttl} -->
<p>Your subscription will expire on {subs_ttl}.</p>
<!-- /IF {subs_ttl} -->
<!-- /BLOCK {url} -->
Providing details of purchased downloads and subscriptions in the Callback template.
Note: The {download_ttl} placeholder outputs a number of days that the download link is valid for, but the {subscription_ttl} outputs a date on which the subscription ends.
BLOCK {new_user}
If the customer has purchased a downloadable product or a site subscription, we may need to create a new user account for this customer to grant them access (assuming the customer is not already logged-in). This block outputs details of the new user account, if one has been generated.
<!-- BLOCK {new_user} -->
<h1>New User Account</h1>
<p>Here is your username and password:<br>
<b>Username:</b> {username}<br>
<b>Password:</b> {password}</p>
<p>To login to our website, visit
<a href="{site_address}content/login/?input_uname={username}
&input_pword={password}&remember=remember">{
site_address}content/login/
</a></p>
<!-- /BLOCK {new_user} -->
Generating a new user account to allow access to a site subscription or downloadable product.
Reporting login details for a new user account in the Callback template.
Below is a summary of all template instructions used in the callback template.
|
Placeholder
|
Output
|
|
IF {successful}
|
This condition should surround all mark-up to be outputted to the customer on receipt of a successfully paid-for order. Unsuccessful order messages should be contained within an ELSE condition.
|
|
BLOCK {contacts}
|
Used to output the contact and address details of the customer.
|
|
BLOCK {shipping}
|
Inside BLOCK {contacts}, displays delivery address details if a delivery address other than the billing address was provided.
|
|
{salutation}
|
Inside BLOCK {contacts}, placeholder for the customer's salutation/title.
|
|
{f_name}
|
Inside BLOCK {contacts}, placeholder for the customer's first name.
|
|
{l_name}
|
Inside BLOCK {contacts}, placeholder for the customer's last name.
|
|
{tel}
|
Inside BLOCK {contacts}, placeholder for the customer's telephone number.
|
|
{tel_eve}
|
Inside BLOCK {contacts}, placeholder for the customer's alternative telephone number.
|
|
{email}
|
Inside BLOCK {contacts}, placeholder for the customer's email address.
|
|
{b_flatno}
|
Inside BLOCK {contacts}, placeholder for the billing address flat/apartment number.
|
|
{b_street}
|
Inside BLOCK {contacts}, placeholder for the billing street address.
|
|
{b_town}
|
Inside BLOCK {contacts}, placeholder for the billing address town.
|
|
{b_state}
|
Inside BLOCK {contacts}, placeholder for the billing address state/region.
|
|
{b_postcode}
|
Inside BLOCK {contacts}, placeholder for the billing address postcode.
|
|
{b_destination}
|
Inside BLOCK {contacts}, placeholder for the billing address country/area.
|
|
{s_name}
|
Inside BLOCK {shipping}, placeholder for the recipient's name, if delivering to a different address.
|
|
{s_flatno}
|
Inside BLOCK {shipping}, placeholder for the shipping address flat/apartment number.
|
|
{s_street}
|
Inside BLOCK {shipping}, placeholder for the shipping street address.
|
|
{s_town}
|
Inside BLOCK {shipping}, placeholder for the shipping address town.
|
|
{s_state}
|
Inside BLOCK {shipping}, placeholder for the shipping address state/region.
|
|
{s_postcode}
|
Inside BLOCK {shipping}, placeholder for the shipping address postcode.
|
|
{s_destination}
|
Inside BLOCK {shipping}, placeholder for the shipping address country/area.
|
|
BLOCK {bad_auth}
|
Displays an error informing the user that the callback page request did not contain all the parameters required to complete the transaction.
|
|
{lead_time}
|
Number of days until the order can be fulfilled. Made up of the delivery time, plus the longest lead time of any out-of-stock items ordered.
|
|
{cart_id}
|
The unique dotAdmin order ID for this order.
|
|
{trans_id}
|
A unique payment ID from the payment provider.
|
|
{literal cart}
|
Displays the shopping cart contents. This placeholder is replaced by the output from the shopping cart template.
|
|
BLOCK {url}
|
Contains information relating to any downloadable products or subscriptions ordered.
|
|
IF {download}
|
Inside BLOCK {url}, used to display a message if the user has ordered a downloadable product.
|
|
IF {subscription}
|
Inside BLOCK {url}, used to display a message if the user has ordered a site subscription.
|
|
{title}
|
Inside BLOCK {url}, the title of the ordered product.
|
|
{site_address}
|
Inside BLOCK {url}, the web address of this site (For example: http://www.site.com/).
|
|
{path}
|
Inside BLOCK {url}, the ID (filename or url) of the product ordered.
|
|
{ext}
|
Inside BLOCK {url}, displays any additional values that must be added to a link to a subscription or downloadable.
|
|
{download_ttl}
|
Inside BLOCK {url}, the number of days for which the download link is valid.
|
|
{subscription_ttl}
|
Inside BLOCK {url}, displays the expiry date of a site subscription.
|
|
BLOCK {new_user}
|
The contents of this block are only displayed if a new user account has been generated for the customer (in order to access a downloadable product or site subscription).
|
|
{username}
|
Inside BLOCK {new_user}, the username for the new user account.
|
|
{password}
|
Inside BLOCK {new_user}, the password for the new user account.
|
|
{site_address}
|
Inside BLOCK {new_user}, the web address of this site (For example: http://www.site.com/).
|
|
{company_name}
|
The name of the company. Taken from the Site Configuration.
|
|
{address_line_1}
|
The company's address. Taken from the Site Configuration.
|
|
{address_line_2}
|
The company's address. Taken from the Site Configuration.
|
|
{town}
|
The company's town/city address. Taken from the Site Configuration.
|
|
{state}
|
The company's state/region address. Taken from the Site Configuration.
|
|
{postcode}
|
The company's postcode. Taken from the Site Configuration.
|
|
{tel}
|
The company's telephone contact number. Taken from the Site Configuration.
|
|
{fax}
|
The company's fax number. Taken from the Site Configuration.
|
|
{e-mail}
|
The company's contact email address. Taken from the Site Configuration.
|
|
