THE RETURN MODE FUNCTION
Related Links: Lookup Function | Passback Function | Return Mode Function | Return Address | PGP Signature

The Return Mode Function (ret_mode) enables you to specify how your customers are returned to your ret_addr (return address) after a successful transaction. By default, your customers are shown a "Continue" page on the secure server after a successful transaction and all name/value pairs are returned using GET.

However, the Return Mode Function allows the customer to bypass the "Continue" page and go directly 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.

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

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 "Continue" screen. 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:
(Does NOT work with ASP or Cold Fusion. See Restrictions below.)
The "post" value can only be used if your ret_addr is a dynamic CGI 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.

The only draw-back to this option is that the entire transaction process takes a bit longer to complete, since our server must first read the contents of your ret_addr page before it can 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 page CANNOT be on a secure server. This will cause an error. It must be an http:// not https://. Your form will still be displayed securely and your customer will not receive a security warning. When using this option, any images called from your ret_addr must be stored on a secure server. If they are not, Netscape users will receive a message stating that "some portions of the document are not secure and will not be displayed."
    • No not include the ret_mode input field in your form if you want the "Continue" screen 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. However, ASP and Cold Fusion applications do not handle the post correctly. If your ASP or Cold Fusion application cannot "see" the incoming name/value pairs, you will not be able to use the ret_mode value of "post." In this case, you will need to remove the ret_mode input line completely from your forms.
    • 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.

    •