THE RETURN MODE FUNCTION
Related Links: Lookup
Function | Passback
Function | Return
Address | Recurring
Postback | PGP
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.)
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 "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:
(See Restrictions
below.)
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 Your" 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.
|
