THE RETURN MODE FUNCTION
Related
Links:
Passback
Function | Lookup
Function | PGP
Signature | Return Address
| Email
Text
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, as well as how transaction information is relayed
to your script.
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.
Please 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:
( 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.
This Error Message List
contains a listing of the possible error messages.
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."
- Do 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, some
ASP and Cold Fusion implementations do not handle this
type of post from our server correctly. 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.
|
