Return Process

Approved URL

After the successful completion of a sale, 2Checkout.com can return the buyer and sale parameters to a script or page on your site. Specifying an approved URL at the account level will direct all buyers to the same URL after a successful checkout. This URL can be entered on the Site Management page by clicking the Account tab followed by the Site Management sub-category.

You may also choose to pass the approved URL on the fly by using the x_receipt_link_url parameter.  This parameter has a few very specific behaviors that should be paid attention so that it can be used effectively.

x_receipt_link_url=http://www.yoursite.com/return

• This parameter will over-ride any approved URL set within your account.
• If your return method is set to Given links back to my Site — This parameter will control where the Click Here to Finalize your Order button takes the buyer after the successful sale.
• If your return method is set to Direct Return or Header Redirect, this parameter will control where the buyer gets directed to automatically after the successful sale.
• The value passed must match the domain registered to the account.

Validation

The MD5 hash is provided to help you verify the authenticity of the passback to your approved URL. The hash is computed using the secret word on the Site Management page and is returned using the key parameter. To validate against the hash, you need to make a string that contains the information described below and pass it in as the value to your scripting languages MD5 function. The MD5 hash is created the same way for a production 2Checkout account and a Sandbox 2Checkout account.

 UPPERCASE(MD5_ENCRYPTED(Secret Word + Seller ID + order_number + Sale Total)) 

The secret word is set by yourself on the Site Managment page. The vendor number is your numerical vendor/seller ID number. The order number is the order number for the sale. The total is the numerical value for the total amount of the sale.Each of our community supported libraries provides a binding to validate the hash on a notification message.

Demo Sales

Please note that the MD5 hash that we return on demo sales is intentionally broken as we use a “1” for the order number when we compute the hash instead of the actual value being returned through the `order_number` parameter. You will need to account for this on your end if you are testing with demo sales by computing the compare hash like below:

UPPERCASE(MD5_ENCRYPTED(Secret Word + Seller ID + 1 + Sale Total))

Example

Below is an example PHP script that validates the hash.

<?php
$hashSecretWord = 'tango'; //2Checkout Secret Word
$hashSid = 1303908; //2Checkout account number
$hashTotal = '1.00'; //Sale total to validate against
$hashOrder = $_REQUEST['order_number']; //2Checkout Order Number
$StringToHash = strtoupper(md5($hashSecretWord . $hashSid . $hashOrder . $hashTotal));

if ($StringToHash != $_REQUEST['key']) {
	$result = 'Fail - Hash Mismatch'; 
	} else { 
	$result = 'Success - Hash Matched';
}

echo $result;

Return Method

2Checkout provides three methods in which the buyer and sale parameters can be returned to your approved URL. You may send the buyer to our order processed page which will display a Click Here to Finalize your Order button to redirect the buyer, you may bypass the order processed page using a header redirect or you can immediately display your approved URL to the buyer while they remain on our server. Your return method can be selected on the Site Management page.

Given links back to my Website

With the Return Method set to Given links back to my website, the buyer will be taken to our Order Processed page after completing a successful purchase. This page will feature a Click Here to Finalize your Order button. When clicked the buyer and collected sale parameters will be directed to the provided approved URL by POST.

Direct Return

With the Return Method set to Direct Return, sale parameters will be posted automatically to the approved URL while fetched by our server and displayed to the buyer. When using this Direct Return function the URL will be masked to the buyer, appearing to still be on the 2Checkout.com domain. This method can be used with redirects as long as each page outputs content more than 255 characters to the browser. If Direct Return encounters a page that redirects without outputting content the process will fail and the buyer will be sent to our standard Order Processed page. This occurs usually with a header redirect, specifically content less then 255 characters. This is a common issue as many developers will set their approved URL to a script that processes the return sales parameters then silently forwards the buyer to another page. This is usually a thank you or download page for intangible products. The best solution is to handle all post-order processing on the page set as your approved URL, including the thank you message. If no redirects are used, meaning the URL is masked by our servers, then relative links will not point to the correct location. This can be corrected with the use of absolute paths on the approved URL page or by simply using a base tag in the head of the document to provide a reference for the relative paths.

Header Redirect

With the Return Method set to Header Redirect the buyer will be immediately returned to your approved URL. Using this method, the sale parameters will be returned along with the buyer using the GET method.

Additional Information

If you are returning the buyer to a script on your end it is important to note that parameter information will typically be returned by POST. Parameters however will be returned by GET if the Header Redirect method is used.