Response Handling

The Hosted Payment Forms (HPF) module has two ways of handling transaction responses:

Online Receipt pages.
Transparent Redirect.

Online Receipt Pages

For merchants who do not have a full-service back-end application, or who do not require direct feedback, the online receipt pages are the easiest solution for providing customers with confirmation receipts and decline notifications.

Receipt Page

The receipt page is displayed whenever a transaction is successful, or approved. It will utilize the same logo as the HPF, and will echo the confirmation text as defined on the HPF edit admin page.

Receipts will display the following data from the transaction:

Payment Amount or amounts in the case of split transactions.
Payment Date
Payment Method is the type & last 4 digits of card or account.
Payment Status is set to approved for cards, pending for ACH, and billing name custom field(s).

A button is included to allow customers to print their receipt.

Decline Page

The decline pages are terminal. They do not provide a means to retry the transaction. Customers will be presented with a generic message telling them the payment was declined, plus:

Payment date
Response Code is a numeric code unique to reason for the decline.
Response Message is the decline notice reflected back from the processor.

Configurable URLs for Handling Responses

It is possible for a merchant to specify the various URLs for “Response Handling” outside of the form setup, if desired. Doing so could lessen the number of forms the merchant requires, but care must be taken to handle configurable URLs in a secure fashion.

In the URL that is used to render the HPF, you can control the back-end behavior by adding even more elements to the URL string. The possible values are explained in the table below. Note that none of them can be sent directly (plain text) and they must be included in a hash for security reasons; however, they do not need to be specified in a hash_key since they are already required to be hashed. For more on HASH and its use, refer to the appendix in this document.

PARAMETER	TYPE	CONTEXT	DESCRIPTION
success_url	string	optional	Used for a non-default (merchant "hosted") successful transaction receipt. Must be a valid URL that will be called if transaction is successful. It needs to be specified inside the hash, but does NOT need to be included in the hash_key.
decline_url	string	optional	Used for a non-default (merchant "hosted") NOT successful transaction receipt. Must be a valid URL that will be called if transaction is declined. It needs to be specified inside the hash, but does NOT need to be included in the hash_key.
cancel_url	string	optional	Must be a valid URL that will be called if user presses Cancel button on HPF. It needs to be specified inside the hash, but does NOT need to be included in the hash_key.
timeout_redirect	string	optional	Must be a valid URL that will be used if the HPF times out on the user. It needs to be specified inside the hash, but does NOT need to be included in the hash_key.
postback_url	string	optional	Must be a valid URL to receive POSTback data.