Relay Response

A Relay Response configuration instructs the payment gateway to return transaction results to the merchant using an HTML form POST to a specified URL on the merchant's Web server. A script or program at the URL can be used to create a custom receipt page from the transaction information. The custom receipt page is then relayed to the customer's browser. Relay Response does not redirect the end user back to your server, but relays your specified Relay URL to the end user through our receipt page instead of displaying our default receipt page. If you would like to redirect the end user back to your server, please provide a link on your Relay URL for this purpose.

If a transaction encounters an error or is part of a partial authorization, and you are using Relay Response, the Authorize.Net payment form reappears, offering an option to try again or enter another form of payment to complete the order. If you are using a customized payment form, you should set x_relay_always to true to prevent the standard Authorize.Net payment form from redisplaying instead of your own customized payment form.

If you are using the Direct Post Method, you should always set x_relay_always to true. For more information on how to integrate your website using the Direct Post Method, see http://developer.authorize.net/guides/DPM/.

The following table describes form fields that can be submitted in order to configure Relay Response. Except for x_relay_always, these settings can also be configured in the Merchant Interface. For more information about configuring Relay Response in the Merchant Interface, please see the Merchant Integration Guide at http://www.authorize.net/support/merchant/.

The form fields are submitted using the following syntax:

FIELD NAME	VALUE	FORMAT	NOTES
x_relay_response	The request for a relay response	TRUE	This field instructs the payment gateway to return transaction results to the merchant using an HTML form POST to the merchant's Web server for a relay response.
x_relay_always	Requests a relay response even for partial authorizations and in case of errors	true, false	This field instructs the payment gateway to return a relay response regardless of whether there are any declines, errors, or partial authorizations.
x_relay_url	The URL on the merchant's Web site to which the payment gateway posts transaction results for a relay response	Any valid URL Including name/value pairs in the URL (anything after a "?") is not recommended	If this field is submitted, the payment gateway will validate the URL value against the Relay Response URL configured in the Merchant Interface. If the URL submitted does not match the URL configured in the Merchant Interface, the transaction will be rejected. If no value is submitted in the HTML Form POST, the payment gateway will post transaction results to the URL configured in the Merchant Interface.

FIELD NAME

VALUE

FORMAT

NOTES

x_relay_response

The request for a relay response

TRUE

This field instructs the payment gateway to return transaction results to the merchant using an HTML form POST to the merchant's Web server for a relay response.

x_relay_always

Requests a relay response even for partial authorizations and in case of errors

true, false

This field instructs the payment gateway to return a relay response regardless of whether there are any declines, errors, or partial authorizations.

x_relay_url

The URL on the merchant's Web site to which the payment gateway posts transaction results for a relay response

Any valid URL

Including name/value pairs in the URL (anything after a "?") is not recommended

If this field is submitted, the payment gateway will validate the URL value against the Relay Response URL configured in the Merchant Interface. If the URL submitted does not match the URL configured in the Merchant Interface, the transaction will be rejected. If no value is submitted in the HTML Form POST, the payment gateway will post transaction results to the URL configured in the Merchant Interface.

Note: If the merchant would like to use the payment gateway hosted receipt page, the Relay Response fields listed above should not be submitted in the transaction request, nor should they be configured in the Merchant Interface. Requesting both the hosted receipt page and a Relay Response will result in a failed implementation.

The following sample code is an example of including the Relay Response request in the HTML Form POST.

Note: The sample code included in this document uses dummy field values in an ASP scripting environment. Because code varies based on Web programming language, it is not recommended that you copy and paste sample code but rather use it as a guide. Additional sample code is available for download from the Authorize.Net Developer Center at http://developer.authorize.net/samplecode.

Sample of payment form request including Relay Response request

<FORM METHOD=POST ACTION=
"https://secure.authorize.net/gateway/transact.dll">
<% ret = InsertFP (APIloginid, sequence, amount, txnkey) %>
<INPUT TYPE=HIDDEN NAME="x_login" VALUE="the merchant's API Login ID">
<INPUT TYPE=HIDDEN NAME="x_version" VALUE="3.1">
<INPUT TYPE=HIDDEN NAME="x_method" VALUE="CC">
<INPUT TYPE=HIDDEN NAME="x_show_form" VALUE="PAYMENT_FORM">
<INPUT TYPE=HIDDEN NAME="x_amount" VALUE="9.95">
<INPUT TYPE=HIDDEN NAME="x_relay_response" VALUE="TRUE">
<INPUT TYPE=HIDDEN NAME="x_relay_url" VALUE="Any valid URL">
<INPUT TYPE=SUBMIT VALUE="Click here for the secure payment form">
</FORM>

When Authorize.Net sends a Relay Response to the merchant's server, if the merchant's web server does not send a positive response after ten seconds, then the connection will time-out and an error is generated for the transaction.

Note: Authorize.Net only posts on ports 80 and 443.

Tips for using Relay Response:

The Relay Response URL specified should be a script that can parse the transaction results posted from the payment gateway. The URL can be a plain HTML page if a static response is desired for every transaction. However, in this case the merchant's Web server should be configured to allow an HTML Form POST to a plain HTML page.
The HTTP header should not be relied on for including customer information such as cookies. When the response is relayed to the customer's browser, HTTP headers are replaced.
Keep in mind that the relay response is rendered on the payment gateway server. Custom receipt pages must incorporate absolute URLs.
Redirects or frames in the relay script are not recommended, because the information might not be transferred properly.