The Return Mode Function

Related Links: Lookup Function | Passback Function | Return Address | Recurring Postback | PGP

Read the RESTRICTIONS below before using this function. As always, test your forms before making them live.

The Return Mode Function (ret_mode) enables you to specify how your customers are returned to your return address (ret_addr) after a successful transaction, as well as how transaction information is relayed to your script.

By default, customers are shown a "Thank You" page on the secure server after a successful transaction. When the customer clicks the "Continue" button all name/value pairs are returned to your script using GET. However, the Return Mode Function allows the customer to bypass the "Thank You" page and be directed to your ret_addr. This enables you to use the gateway services "transparently."

This function also has a feature enabling you to receive error messages and failures (declines) returned to a specified script on your server. (See below.)

There are two values that can be used with the Return Mode Function. They are "post" and "redirect". Each has a specific function, as explained below:

Redirect

The "redirect" ret_mode value can be used if your ret_addr is a static HTML document. After a successful transaction, your customer is automatically redirected to your ret_addr, by-passing the "Thank You" page. Since this is a simple redirect, no Passback or Lookup values can be returned.

Redirect example

To use the Return Mode Function simply add the following HTML code to your order form.

<input type="hidden" name="ret_mode" value="redirect" />

Post

The "post" value can only be used if your ret_addr is a dynamic page/script, such as PHP, ASP, or Perl script. After a successful transaction, the information you have requested from the processing server will be posted to your ret_addr. All Lookup and Passback name/value pairs will be returned via the POST.

Post example

To use the Return Mode Function simply add the following HTML code to your order form.

<input type="hidden" name="ret_mode" value="post" />

Post Example with declines and error messages

Add the HTML code to your order form as shown above. If you would like decline and error messages also sent to your ret_addr, add the following HTML code to your form.

<input type="hidden" name="post_back_on_error" value="1" />

This feature is very powerful, giving you complete control of the entire transaction process. Responses will appear as follows:

  • If a transaction is declined, you will receive a name/value pair of "err=Text message of the error" along with the name/value pairs for each passback variable requested.
  • If an internal error is encountered, you will receive a name/value pair of "die=1".
  • If the transaction is successful, neither of these will appear.

Restrictions & Warnings

  • When using ret_mode with the "redirect" option, your ret_addr page should reside on a secure server. Otherwise your customer's will receive a security warning.
  • When using ret_mode with the "post" option, your ret_addr url may be on a secure (https) or non-secure (http) server. In either case, the page will be displayed securely.
  • Do not include the ret_mode input field in your form if you want the "Thank You" page to appear.
  • When using ret_mode, your ret_addr must be an absolute URL, not a relative URL. (i.e. http://www.yoursite.com/cgi-bin/return.cgi is absolute. ../cgi-bin/return.cgi is relative.) In addition, all links located on your ret_addr page must also be absolute URLs.
  • If ret_mode is not implemented correctly, customer's transactions will be cancelled. However, you will receive an email detailing the ret_mode error. (If your ret_addr cannot be read by our server, you will not receive an error message and your customer's account will be billed.)
  • The ret_mode function uses a standard http 1.1 post. If your ASP or Cold Fusion application cannot "see" the incoming name/value pairs, you will need to consult your documentation/system admin.
  • The Return Mode Function is MUCH more dynamic than the standard GET method used to return customers to your site. Please be aware that if your ret_addr is not available, unreadable, incomplete, times out, etc., your customer's account will have already been billed and they will receive an error message. Only use the Return Mode Function if you are very familiar with CGI scripting. Always test your applications before making them available to your users.
  • For security reasons, you must use a standard port for post-back data. (port 80 for http or port 443 for https) In other words, a ret_addr of http://www.yoursite.com:9876 will not work correctly.