E-xact Knowledge Base :: Hosted Checkout Integration Manual

Search the Knowledgebase

Browse by Category

Hosted Checkout Integration Manual

* To download a PDF copy of the Hosted Checkout Integration Manual click the "Export to PDF" option on the right hand side.

2 Introduction
3 Customer Experience
3.1 Customer Confirms Order on Merchant's Website
3.2 Customer Lands on the Hosted Checkout Payment Form
3.3 Customer Experience: Credit Card Payment
3.3.1 Credit Card Payment is Processed
3.3.2 Credit Card Payment Customer Receipt
3.4 Customer Experience: INTERAC Online Payment
3.4.1 Customer is Redirected to INTERAC Online
3.4.2 Customer Chooses Their Bank at INTERAC Online
3.4.3 INTERAC Online Payment is Processed
3.4.4 INTERAC Online Customer Receipt
3.5 Appearance
4 Configuration
4.1.1 Payment Record: General Settings
4.1.2 Payment Page Record: Appearance Settings
4.1.3 Payment Page Record: Terminals Settings
4.1.4 Payment Page Record: Email Settings
4.1.5 Payment Page Record: Relay Response Settings
4.1.6 Payment Page Record: Transaction Key Setting
5 Character Encoding
6 Payment Form Fields
6.1 Essential Fields
6.2 Transaction and Display Fields
6.3 Order and Customer Detail Fields
6.4 Unsupported Fields and Unsupported Authorize.net
Functionalities
7 Relay Response Mode
7.1 Standard Authorize.net Fields
7.2 Standard Authorize.net Fields (Credit Card Only)
7.3 E-xact Additional Fields
7.4 E-xact SOAP Response Fields
7.5 E-xact SOAP Response Fields (Credit Card Only)
7.6 Response Reason Codes and Text
7.7 Common Bank Response Codes
7.8 Address Verification Result Codes
7.9 CVV2 Verification Indicator Codes
7.10 CVV2 Result Codes
8 Receipt Link / Silent Post
9 Example Payment Forms
9.1 Basic Example
9.2 Example Including Relay Response
9.3 Resulting Payment Form
9.4 Example with Order Details
10 Implementation and Testing Guide
10.1 Generation of the Checkout Form
10.1.1 Calculating the “x_fp_hash” value
10.1.2 Testing the “x_fp_hash” calculation
10.1.3 Tying the Payment to a Particular Order
10.2 Relay Response Implementation
10.2.1 Generated HTML
10.2.2 Customer Cookies
10.2.3 Relay Response Signature
10.2.4 Sample Relay Response POST
10.2.5 Relay Response Sample Code
11 Customer's Browser Requirements
11.1 Cookies
11.2 JavaScript
12 Authorize.net SIM Compatibility

2 Introduction
Hosted Checkout is a securely hosted web payment form
designed to accept Internet based E-commerce transactions.

With Hosted Checkout customers can pay with their credit cards
or directly from their bank account through INTERAC Online
(IOP). IOP enables a customer to pay directly from their bank
account and utilizes the customer’s existing online banking
interface to authorize the transaction and facilitate payment.
The customer’s online experience will include a redirection to
their online banking website from Hosted Checkout. Once
authenticated the customer is returned to the Hosted Checkout web page
where the process is completed and a receipt is displayed to
them.

With Hosted Checkout in place a merchant is no longer exposed to the
sensitive payment details required to process a payment.
Additionally, the merchant has access to an expanding tool kit
of payment options and fraud prevention tools without the need
for additional development.

Hosted Checkout redirects the customer to a point of sale form
hosted by E-xact Transactions for payment collection. To
accomplish this the merchant displays a "Checkout" button
within an HTML form on their website that will submit a
POST request to the following URL:

https://checkout.e-xact.com/payment

Within the parameters of this HTML form the merchant
specifies the location of the Payment Page along with payment
details and authentication information. These parameters are
usually “hidden” in the HTML code.

At the end of the payment process all parameters that define
the status of the transaction can be returned to the merchant in
real-time.

The appearance and payment options displayed on the Payment
Page are configured through an online management interface
available to all E-xact merchants.

At the end of the payment process all required parameters that
define the status of the transaction are returned to the Merchant.

This document will also focus on a specific payment type
available through Hosted Checkout called Interac Online, or IOP,
and covers the configuration of the merchant's account at E-xact,
the request parameters for the payment form and how they are
processed, and includes request examples.

3 Customer Experience
A successful scenario for a payment sequence from the customer’s
perspective would be as follows:

3.1 Customer Confirms Order on Merchant's
Website
For example, this illustration shows a fictitious checkout page that
is the last step in ordering items from the website
http://store.merchant.com (Illustration 1).

When the customer clicks the highlighted “Checkout” link they
leave the merchant's site and land on E-xact Transactions’ Hosted Checkout
payment form (Illustration 2).

3.2 Customer Lands on the Hosted Checkout
Payment Form

The payment page corresponding to this example payment form is
configured for both credit card and INTERAC Online payments and the
customer can easily choose between these two options.

Section 3.3 follows the customer experience for the credit card payment
option while section 3.4 illustrates the customer experience for the
INTERAC Online option.

3.3 Customer Experience: Credit Card Payment
The customer enters their credit card information in the payment form
(Illustration 2) and clicks the “Pay With Your Credit Card” button. The
payment is immediately processed while the customer is shown a wait
screen.

3.3.1 Credit Card Payment is Processed

3.3.2 Credit Card Payment Customer Receipt
If the credit card information is correct, the payment is processed and the
customer shown their receipt:

Note: See Section 7 Relay Response Mode, for the option of the
merchant's web server producing the receipt page.

3.4 Customer Experience: INTERAC Online Payment
When the customer hits the “Pay From Your Bank Account” button they
are taken to the next step in the payment sequence (Illustration 5). Note:
this page is not normally visible to the customer as it redirects automatically
when the web browser has JavaScript turned on. If JavaScript is disabled
they will need to hit the “Continue Payment” button.

3.4.1 Customer is Redirected to INTERAC Online

3.4.2 Customer Chooses Their Bank at INTERAC Online
After the customer selects their bank (Illustration 6), they are directed to log in
at the bank's website, select the appropriate bank account, and are then
redirected back to the Hosted Checkout site. The payment is immediately finalized.

3.4.3 INTERAC Online Payment is Processed

3.4.4 INTERAC Online Customer Receipt
When the payment has been finalized, the receipt is displayed to the customer
(Illustration 8).

3.5 Appearance
The merchant can customize the appearance of their Hosted Checkout page as follows:

1. All pages (except for the Interac Online page) can be styled to match the
    merchant's website design by configuring a colour scheme and specifying the
    logo to be displayed.

2. The merchant’s server can be set to render entirely the last page (customer
    receipt display) through Relay Response. See Section 7. Relay Response
    Mode.See Illustration 4 and 8 for examples of customer receipts.

4 Configuration
The Hosted Checkout payment page configuration determines how each
payment is processed. This configuration covers payment processing
presentation and functionality such as Relay Response Mode and email
notification.

The redirect to Hosted Checkout's payment form requires the configuration of at least
one Payment Page, each identified by a unique "Payment Page ID". This ID
is passed in as the "x_login" parameter when the merchant redirects to the
Payment Page to process a transaction. See Section 6.1 Essential Fields

Payment pages are administered through the "Hosted Checkout" tab,
accessible only to administrators (Illustration 9). The payment page record
describes several aspects of the payment page form:

General Settings: Defines the Name and Location of the Payment Pg
Appearance: Defines the look and feel of the Payment Page
Terminals: How payments are processed
Email: Notifications about orders and submission errors for the
merchant,sending customer receipts by email
Relay Response: Relay Response URL and security keys
Keys: Main key for the Payment Page Redirect

Merchants can add as many payment pages as required. This allows the support
of:

Multiple shopping carts
Multiple languages
Various processing options (i.e. one payment page for INTERAC Online
payments, one payment page for credit card payments only, etc.)
A dedicated demo payment page

To add a new payment page, click the “New Payment Page” link.

To change an existing payment page, click on its Payment Page ID.

Additionally, existing payment pages can be previewed or deleted on this
tab.

4.1.1 Payment Record: General Settings
The General Settings tab of a payment page defines its name and location
(Illustration 10).

The “Return to Your Site” URL is used for the “Return to Hosted Checkout
Example Shop” link in Illustration 2. It is also used for timeout pages
allowing the customer to return to the merchant's website.

The Payment Page ID is generated by the system and cannot be changed.
It corresponds to the redirect parameter “x_login”. Payments may be
processed in test or live mode. This option may be preconfigured (as shown
here) depending on terminal settings. For instance, the example account
here has no live terminals available. Test mode can also be triggered with
the redirect parameter “x_test_request”; see Section 6.2 Transaction and
Display Fields.

For “Receipt Link Method” details, please see Section 8 Receipt Link/Silent
Post. This setting may be overridden with redirect parameter
“x_receipt_link_method”. The “Receipt Link Text” and URL appear as the
link definition shown in Illustration 4, “Go back to Example Shop”. They
may be overridden with redirect parameters “x_receipt_link_text” and
“x_receipt_link_url”.

4.1.2 Payment Page Record: Appearance Settings
The appearance of the Hosted Checkout pages for a payment page is configured in the
Appearance tab where the language, logo, and background and text colours
can be set (Illustration 11).

4.1.3 Payment Page Record: Terminals Settings
The payment processing terminal options can be set in the Terminals tab
(Illustration 12).

For INTERAC Online processing choose one of the following options:

Offer both Credit Card and INTERAC options
Offer INTERAC option only
Offer INTERAC option only (bypass the first page at checkout)

Notes:
- Option 1 corresponds to the configuration for the Hosted Checkout pages shown in
Section 3 Customer Experience
- With Option 2 the credit card payment form will not be shown to the
customer.
- With Option 3 the customer experience is the same as Option 2 except
that the page in Section 3.2 Customer Lands on the Hosted Checkout
Payment Form, is skipped.
- Select the desired merchant/terminal combinations under the sections
“Credit Card Processing”, “INTERAC Online Processing”,
“Test Processing – Credit Card”, “Test Processing – INTERAC”.

In the sample account shown there are no live processing terminals
available; therefore that option is not displayed.

Note: When a payment request is made in test mode the “Pay from your
Bank Account” button on the Hosted Checkout payment form will not redirect to the
Interac Online site, but to a page hosted by E-xact that simulates an
INTERAC Online payment.

4.1.4 Payment Page Record: Email Settings
Hosted Checkout can be configured to send order confirmation emails to the
customer (Illustration 13).

If the Email Enabled option is checked, the payment form will show an email
field for the customer to fill in. A copy of this email will be sent to the
designated Notification Email as well. The email will be sent from the address
configured in the “From” field.

The Notification Email address will also receive emails in the case that errors
occur during processing. The most common incident of a processing error
during Hosted Checkout is due to invalid payment form requests (for example,
if the “x_fp_hash” is invalid). Therefore, Notification Email is not an optional
field.

The order notification email can also be configured with optional merchant
defined headers and footers.

4.1.5 Payment Page Record: Relay Response Settings
The Relay Response mode of Hosted Checkout (Illustration 14) is covered in further detail
in Section 7. Two values are needed:

Relay Response URL
Relay Response Key

This tab also contains the Silent Post option. Populating the Silent Response
URL enables this feature. See Section 8 Receipt Link/Silent Post.

4.1.6 Payment Page Record: Transaction Key Setting
The parameter x_fp_hash validates that the merchant’s server generated the
redirect parameters correctly. Its calculation is based on the transaction key
along with other redirect parameters. Transaction key is generated and set in the
Keys tab (Illustration 15) as a random string by E-xact’s servers.

The key can be changed with the Generate New Merchant Key button.

Note: Changing the transaction key will break existing links to the payment
page.

5 Character Encoding
Incoming parameters should be encoded in UTF-8 to ensure correct text display
and processing.

6 Payment Form Fields
The merchant interfaces with Hosted Checkout by displaying an HTML form on a website
page that submits a POST request to Hosted Checkout at
https://checkout.e-xact.com/payment. Using fields that are usually HTML-
hidden within the form the merchant specifies the particulars about the payment.
The fields supported by Hosted Checkout are described in this section.

6.1 Essential Fields
The following parameters are required, and validated with each request. If one
is missing or the validation fails the customer will see an error page. The
merchant will also receive an email explaining the problem.

Field	Value	Description
x_login	Varies by merchant	Maximum length 20, the Payment Page ID from the Administration Console. Case-sensitive.
x_fp_sequence	Chosen by merchant	Can be a random number. Used in “x_fp_hash” calculation in order to make it unique but not used otherwise. Returned with Relay Response / Silent Post / Receipt Link. No length restriction
x_fp_timestamp	Time in seconds since January 1, 1970. UTC, Coordinated Universal Time	Requests expire after 15 minutes / 900 seconds.
x_amount	Positive number	Total dollar amount to be charged inclusive of freight and tax; Maximum Length 15
x_fp_hash	String	HMAC-MD5 hash from the merchant’s transaction key and concatenation of the values for “x_login”, “x_fp_sequence”, “x_fp_timestamp”, “x_amount”, and (if given) “x_currency_code” – all separated by the “^” character. Note that if “x_currency_code” is not present, then a “^” character is still added. The transaction key is generated within the payment page configuration section of the Administration console tab, “Keys”.
x_show_form	PAYMENT_FORM	Case-sensitive

Notes:
- The “x_fp_hash” parameter serves solely as verification that the form was
   generated by the merchant's server, and not by the customer or a third party.
   Its calculation depends on the merchant’s private Transaction Key. The
   Transaction Key is discussed in Section 4.1.6 Payment Page Record:
   Transaction Key Setting.
- The “x_show_form” parameter is required in order to stay compatible with
   the Authorize.Net protocol. See Section 12 Authorize.net SIM Compatibility

6.2 Transaction and Display Fields
These parameters are validated as indicated below. If invalid, one of the
following two scenarios will occur:

- The customer's browser will display an error page and the merchant
   will be notified by email
- A default value will be substituted
- The parameters are passed on as received by Hosted Checkout in:

Notifications to the merchant about errors
Relay response posts (see Section 7 Relay Response Mode)
Receipt Link GET/POST/REDI

Name/Area	Validation	Explanation
Processing Fields
x_test_request	TRUE/FALSE	Process payment in test mode. Case-sensitive.
x_type	AUTH_CAPTURE / AUTH_ONLY	The type of the transaction. AUTH_CAPTURE is Purchase/Sale. AUTH_ONLY known as Authorization / Preauthorization Note: There is no Interac preauthorization. An Interac payment with “x_type” of AUTH_ONLY will be processed as AUTH_CAPTURE.
Receipt Page Fields
x_receipt_link_method	LINK/GET/POST	Specifies the type of link made back to the merchant's website. Case-sensitive.
x_receipt_link_text	Any text	Hyperlinked text or submit button value. Is displayed with further formatting. With GET or POST a form is generated with hidden fields that contain the result of the processed transaction. If empty, default value "Return to Merchant website title" is used. Merchant website title is set in the Hosted Checkout interface.
x_receipt_link_url	Valid URL	Target of hyperlinked text or action for HTML GET/POST. If empty or not a valid URL, the default value from the Hosted Checkout interface is taken.
Fields Common to Payment Form and Receipt Page
x_logo_url	Valid URL	Displayed on header of Payment Form and Receipt Page. If empty or not a valid URL, the default value from the Hosted Checkout interface is taken.
x_color_background	HTML colour name or hex code	Background colour of the Payment Form and Receipt Page. If empty or invalid, default value from the Hosted Checkout interface is used.
Email Setting Fields
x_email_customer	TRUE/FALSE	Should a confirmation email be sent to the customer; default is set in the Administration Console's payment page configuration section.
x_merchant_email	Valid email address	Email address to which the merchant's copy of the customer confirmation email should be sent. If a value is submitted an email will be sent to this address as well as the addresses configured in the payment page configuration section of the Administration Console. No email will be sent to this address if it does not meet standard email format checks.
Transaction Data FieldsTransaction Data Fields
x_currency_code	USD or CAD	Currency of the transaction. Case sensitive. (INTERAC Online supports only CAD)

6.3 Order and Customer Detail Fields
The parameters below describe details about the order and the customer and
all are optional. They are passed as received by Hosted Checkout via:

Notification emails to the merchant about errors
Relay response POST's (see Section 7 Relay Response Mode)
Receipt Link GET/POST/REDI

Order Information Fields	Explanation
x_cust_id	Not validated. Unique identifier for the customer associated with the transaction. Not displayed to the customer
x_invoice_num	Merchant-assigned invoice number. Truncated to the first 20 characters and becomes part of the transaction. It appears in column “Ref Num” under Transaction Search and “TRANS. REF” in the CTR (customer transaction record).
x_customer_tax_id	Not validated. Tax ID of the customer. Not displayed to the customer.
x_line_item	See note below.
x_po_num	Purchase order number. Truncated to the first 20 characters and becomes part of the transaction. It appears in column “Customer Reference Number” under Transaction Search. It does not appear in the receipt.
x_description	Not validated. Description of the transaction. Not displayed to the customer.
x_reference_3	Additional Reference Data. Maximum length 30 and becomes part of the transaction. It appears in column "Reference Number 3" under Transaction Search. It does not appear in the receipt.
Customer Name and Billing Address Fields
x_first_name	For billing address
x_last_name	For billing address
x_company	For billing address
x_address	For billing address
x_city	For billing address
x_state	For billing address
x_zip	For billing address
x_country	For billing address
x_phone	For billing address
x_fax	For billing address
Customer Shipping Address Fields
x_ship_to_first_name	For shipping address
x_ship_to_last_name	For shipping address
x_ship_to_company	For shipping address
x_ship_to_address	For shipping address
x_ship_to_city	For shipping address
x_ship_to_state	For shipping address
x_ship_to_zip	For shipping address
x_ship_to_country	For shipping address
Additional Customer Data Field
x_customer_ip	IP address of the customer.
x_email	Email address to which the customer's copy of the confirmation email is sent. No email will be sent if the email address does not meet standard email format checks.
Additional Amount Fields
x_tax	Non-negative Number. The tax in dollars.
x_tax_exempt	TRUE/FALSE
x_freight	Non-negative Number. Freight charge in dollars.
x_duty	Non-negative Number. Duty in dollars.

Note regarding "x_line_item": Fields with this name contain itemized order
information delimited by the three characters, <|>

The format is:

Item ID<|>Item Name<|>Item Description<|>Item Quantity<|>Item Price<|>Item Taxable(YES/NO)<|>

This parameter may occur several times (with different items). The item
details are displayed on the Hosted Checkout payment form and receipt page
for the customer's reference.

Notes on Additional Amount Fields: the “x_tax”, “x_freight”, “x_duty”
amounts are for display within the order information and order confirmation
emails only. Hosted Checkout performs no calculations with these numbers. They are
passed back to the merchant with Relay Response, Silent Post, and Receipt
Links.

6.4 Unsupported Fields and Unsupported Authorize.net
Functionalities
The following fields and their corresponding Authorize.net functionality are
not supported by Hosted Checkout:

Field	Comment
x_header_html_payment_form	Ignored, not validated
x_footer_html_payment_form	Ignored, not validated
x_header_html_receipt	Ignored, not validated
x_footer_html_receipt	Ignored, not validated
x_recurring_billing	Flagged as an error, if present and not “NO”.
x_bank_aba_code	Flagged as an error, if present and not “NO”.
x_bank_acct_type	Flagged as an error, if present and not “NO”.
x_bank_name	Flagged as an error, if present and not “NO”.
x_echeck_type	Flagged as an error, if present and not “NO”.
x_card_num	Flagged as an error, if present and not “NO”.
x_exp_date	Flagged as an error, if present and not “NO”.
x_card_code	Flagged as an error, if present and not “NO”.
x_trans_id	Flagged as an error, if present and not “NO”.
x_auth_code	Flagged as an error, if present and not “NO”.
x_authentication_indicator	Flagged as an error, if present and not “NO”.
x_cardholder_authentication_value	Flagged as an error, if present and not “NO”.
x_duplicate_window	Flagged as an error, if present and not “NO”.

7 Relay Response Mode
The Relay Response mode of Hosted Checkout involves sending transaction
response information to a server specified by the merchant. The response
from the merchant server is then passed on to the customer's browser as a
receipt for the transaction. It allows the merchant to tailor the receipt page to
the individual customer and update their web server in real time (for
example, to empty the shopping cart).

The merchant is required by Interac to display the values of the two fields to
the customer:

exact_issname (Issuing Bank Name)
exact_issconf (Issuing Bank Confirmation Number)

See Illustration 8: Customer Receipt for an INTERAC Online Payment.

No sensitive transaction related data is transmitted to the merchant server.

Usually the Relay Response step is only performed for successful transactions.
However, if the customer's payment attempts fail three times a “Transaction
Declined” message is posted to the merchant's server for Relay Response.

If the merchant server response is not received within 11 seconds, the
customer will be shown the ordinary Hosted Checkout receipt page.

In order to trigger Relay Response mode, set the following parameters in
the redirect request:

Field	Value	Description/Comment
x_relay_response	TRUE	Required for Relay Response. Case sensitive (FALSE is not allowed)
x_relay_url	Hosted Checkout Configuration	Optional. The URL to which the gateway posts the response. Validated with the value configured in the Hosted Checkout interface. If empty, the URL from the Hosted Checkout interface is used.

The following fields are sent in a POST request to the merchant supplied
Relay Response URL. There are four different categories of fields of which
the first three are covered in the following tables:

1. Standard Authorize.net “x_” parameters.
2. E-xact Hosted Checkout Relay Response fields.
3. Most of the response fields returned for the equivalent E-xact Web service
     SOAP request.
4. Most of the POST parameters from the initial request from the merchant's
     website to the Hosted Checkout payment form. This includes, “x_login”, “x_amount”
     etc.
5. The server response should be in HTML format, and is passed on to the
     customer's browser for final display.

7.1 Standard Authorize.net Fields
The fields below apply to both INTERAC Online payments and credit card
payments.

Field	Description	Explanation
x_response_code	Response code	1 for “Approved”, 2 for “Declined”, 3 for “Error”
x_response_subcode	Response Subcode	Internal value. Future use.
x_response_reason_code	Response Reason Code	See table under Section 7.6 Response Reason Codes and Text, below.
x_response_reason_text	Response Reason Text	See table under Section 7.6 Response Reason Codes and Text, below.
x_auth_code	Approval Code	Authorization number of the transaction
x_trans_id	Transaction Id	Unique identifier, generated by E-xact Transactions.
x_MD5_Hash	MD5 Hash	MD5 hash, in hexadecimal, of the concatenation of these strings: Payment Page Configuration Relay Response Key “x_login” Transaction ID (field “x_trans_id”) Amount, two digits after the period ($100 is used as “100.00”)

7.2 Standard Authorize.net Fields
(Credit Card Only)
The fields below do not apply to INTERAC Online payments and will be empty in this case.

Field	Description	Explanation
x_avs_code	Address Verification Result Code	See table under Section 7.8 Address Verification Result Codes
x_cvv2_resp_code	CVV2 Response Code	See table under Section 7.9 CVV2 Verification Indicator Codes
x_cavv_response	CAVV Response Code	Not supported. Field is empty.

7.3 E-xact Additional Fields

Field	Description	Explanation
exact_wsp_version	WSP Protocol Version	Latest value 1.7
exact_ctr	Receipt	E-xact generated Customer Transaction Record (CTR)
exact_issname	Issuer Name	The name of the customer's bank. The merchant is required by INTERAC to display this field to the customer.
exact_issconf	Issuer Confirmation Number	The confirmation number generated by the customer's bank. The merchant is required by INTERAC to display this field to the customer.

7.4 E-xact SOAP Response Fields
The fields below apply to both INTERAC Online payments and credit card
payments.

Field	Description	Explanation/Details
Authorization_Num	Authorization number	The authorization number returned by the financial institution.
Bank_Message	Describes the Bank_Resp_code	Message provided by the financial institution.
Bank_Resp_code	2 or 3 digit code	See table under Section 7.7 Common Bank Response Codes.
Bank_Resp_code_2	2 digit code	A secondary response returned by the financial institution.
CardHoldersName	Customer's name	Up to 30 characters. This name will also appear under the Administration Console's Transaction Search tab. For INTERAC Online payments, this field is only useful if the merchant populates “x_first_name” and “x_last_name” in the redirect.
Client_Email	Email Address as provided by customer	(Not passed on to the financial institution.)
Customer_Ref	Merchant Defined	The value of “x_po_num” as passed in from the merchant's website
DollarAmount	The amount of the transaction	The amount of the transaction in dollars and cents.
Exact_Message	Message about the Processing status	Accompanies the “Exact_Resp_code” field
Exact_Resp_code	Processing Status	The processing status of the transaction. Please refer to the Knowledge Base for further information. The “Transaction_Error” property will be “True” if this property is not “00”.
Language	Language of the CTR	0 for English, 4 for French
Reference_No	Merchant Defined	The value of "x_invoice_num" as passed in from the merchant's website
SequenceNo	Sequence Number	Sequentially incremented number generated by E-xact and passed through to the financial institution
TransactionCardType	Payment Type	The type of credit card, e.g. "VISA", "MASTERCARD", or for INTERAC Online payments, "Interac Online Debit"
Transaction_Approved	Flag indicating transaction approval	Indicates that the bank approved a transaction and there are no pending errors
Transaction_Error	Error flag	Indicates that there was an error during the processing of the transaction. Values are "true" or "false".
Transaction_Tag	Tag of the transaction	Identifier for the tagged transaction. Same as "x_trans_id"

7.5 E-xact SOAP Response Fields
(Credit Card Only)
The fields below do not apply to INTERAC Online payments and will be
empty for IOP transactions.

Field	Description	Explanation
AVS	Address Verification Result	See table under Section 7.8 Address Verification Result Codes
CAVV	Cardholder Authentication Verification Value	Value returned by the Access Control Server to indicate that a cardholder has been validated
CAVV_Algorithm	Method used to calculate CAVV	Sent in authorization request.
CAVV_Response	Validity of the CAVV value provided	Not supported
CVD_Presence_Ind	How the CVV2 value is handled	See table under Section 7.9 CVV2 Verification Indicator Codes
CVV2	Authentication Code returned by the bank	See table under Section 7.10 CVV2 Result Codes
CardHoldersName	Customer's Name	Up to 30 characters
Card_Number	The credit card number	This value is masked
Retrieval_Ref_No	AVS related	The reference number returned with an AVS result
Secure_AuthRequired	3-D Secure Field	Indicates the status of a 3-D Secure transaction. Used for internal audit.
Secure_AuthResult	3-D Secure Field	Indicates the status of a 3-D Secure transaction. Used for internal audit.
ZipCode	Customer address field	Used for qualifying transactions.

7.6 Response Reason Codes and Text
The fields below are the Response Reason Codes supported by Hosted Checkout.

Response Reason Code	Response Reason Text
1	Transaction has been approved
2	Transaction has been declined
3	An error occurred while processing the transaction

7.7 Common Bank Response Codes
The codes below appear in the field “Bank_Resp_Code”.

Bank_Response_Code	Message
000	Approved
200	Authorization Declined
218	Request Denied
292	Banking Network Down Please Retry
294	Busy Please Retry
297	Error - Retry
299	Error - Retry

7.8 Address Verification Result Codes
The values below occur in the fields “AVS” and “x_avs_response”.

Value	Explanation
A	Address matches but ZIP/Postal code does not
B	Address not provided
E	AVS Error
G	Card issuer does not support AVS
N	No match on address and ZIP/Postal Code
P	AVS does not apply to the transaction
R	System unavailable - Retry
S	Card issuer does not support AVS
U	No address available
W	9 digit ZIP/Postal Code match, address does not
X	Address and 9 digit ZIP/Postal Code match

7.9 CVV2 Verification Indicator Codes
The values below occur in the field “CVD_Presence_Ind”. Note that if the
value is not 0 the cardholder provides it.

Value	Explanation
0	Not supported by processing terminal or card type
1	Value provided by cardholder
2	Cardholder states that value on card is illegible
9	Cardholder states that data is not available

7.10 CVV2 Result Codes
The values below occur in the fields “CVV2” and “x_cvv2_resp_code”.

Value	Explanation
M	Match
N	No Match
P	Not Processed
S	Should have been provided
U	Issuer unable to process request

8 Receipt Link / Silent Post
In addition to the Relay Response protocol, merchants can configure two
additional notification methods for completed payments:

- Silent Post protocol triggers ‘successful payment’ notifications to the
   merchant's servers. For the merchant's server this is the same as relay
   response except that the response from the merchant server is ignored by
   Hosted Checkout and the customer is shown the usual receipt page.
   To configure Silent Post, add a “Silent Post URL” to the “Relay Response”
   tab of the Administration console.
- A Receipt Link can be configured to appear on the page once payment is
successful. This link is set in the “General” tab of the Administration
console. The options are LINK, an ordinary hyperlink, GET, a form with
GET action, POST, a form with POST action, and REDI, an automatic re-
direct back to the merchant storefront that also posts a result form back to
the merchant server.

One key difference between the Silent Post and Receipt Link methods
is that the former is performed automatically while the user triggers the
latter (except in the case of REDI).

The fields and values sent to the merchant's servers for Relay Response
and Silent Post are the same. However, the Receipt Link method does not
include the SOAP fields and values.

The Receipt Link method does not apply normally when Relay Response
mode is used. With Relay Response, the merchant’s server generates the
receipt page where the receipt link would appear. The E-xact Transactions'
generated receipt page shown only if there is a communication failure with
the merchant's server for Relay Response.

9 Example Payment Forms
Below are a few examples of the form placed on the merchant's website
that will redirect the customer to the Hosted Checkout payment form.

9.1 Basic Example
This basic example only specifies the payment page record to use,
“x_login”, and the amount to charge, “x_amount”.

Note:

- Replace the value for x_login with a payment page id of the merchant's
   account, and x_amount with the dollar amount payable by the customer.
- The method to generate the sequence number, x_fp_sequence is chosen
by the merchant.
- x_fp_timestamp is the timestamp created when the form is generated.
It is equal to the number of seconds since January 1, 1970 in UTC
(Coordinated Universal Time).
- x_fp_hash is calculated as the HMAC-MD5 from the Transaction Key of
the payment page with a given x_login and the string
“x_login^x_fp_sequence^x_fp_timestamp^x_amount^” with the
   particular values replaced.
- “x_show_form” is always equal to “PAYMENT_FORM”.

9.2 Example Including Relay Response
This basic example utilizes relay response mode:

Only one additional parameter is added, compared to the example in Section
9.1:

-->
9.3 Resulting Payment Form
For the two examples in Sections 9.1 and 9.2 the payment form presented to the
customer will appear as below. Colours and title may be customized. The
options credit card and INTERAC forms appearing is controlled by the payment
pages’ Terminals configuration.

9.4 Example with Order Details
The merchant has the option of specifying additional details regarding the
customer’s order:

Order Items including quantity and unit price.
Shipping and handling charges
Taxes
Duties

These values are communicated to Hosted Checkout with the independent
parameters “x_line_item”, “x_freight”, “x_duty”, and “x_tax”. For example,
this form uses “x_line_item”, ”x_freight”, and “x_tax” but not “x_duty”:

Note:

- The x_line_item parameter may be repeated with each occurrence
corresponding to an item in the order. See Section 6.3 Order and Customer
Detail Fields, for the format.
- Adding order items is independent of triggering Relay Response.

10 Implementation and Testing
Guide
If a merchant is not using an Authorize.net compatible shopping cart package,
some web programming will be required. This section deals with resources
provided by E-xact that the merchant's web developer can utilize for
implementation and testing.

10.1 Generation of the Checkout Form
The main Hosted Checkout interface, displayed after a payment page is
configured, is reached via a checkout form on the merchant's website which
posts to the Hosted Checkout URL at https://checkout.e-xact.com/payment. Section 9
Example Payment Forms, lists some examples for the required HTML code.

10.1.1 Calculating the “x_fp_hash” value
One of the input fields to be calculated for each checkout form separately is the
“x_fp_hash” value. This is because one of the inputs that this value depends on is
a time stamp: a payment request with a time stamp which is 15 minutes or older
will be rejected by Hosted Checkout.

The “x_fp_hash” calculation is performed using the HMAC-MD5 key (the
Transaction Key from the payment page configuration) and the HMAC-MD5
message, or payload, as the concatenation of “x_login”, “x_fp_sequence”,
”x_fp_timestamp”, “x_amount”, and (if used) “x_currency_code” – all separated
by the “^” character (see also Section 6.1 Essential Fields). The value of the
transaction key can be found within the “Keys” tab of the payment page
configuration as seen in the figure below.

Note that even if the “x_currency_code” field is left empty, the payload for the
hash calculation should end with the ^ character.

E-xact's Knowledge Base, at http://kb.e-xact.com provides implementations
for this calculation in many programming languages including PHP, Java,
Python and Perl. See the Hosted Checkout category.

Field	Value
x_login	WSP-GOODS-70
x_fp_sequence	123454321
x_fp_timestamp	1228953556
x_amount	100.00
Transaction Key	AL81Li7D4laXYDtpfgO_lInQ

For example, using the values in the table above, the resulting HMAC-MD5 is
calculated with the payload of WSP-GOODS-70^123454321^1228953556
^100.00^ and has the value, dba76cedb7847547fd964fc903e9f2c

Note that if the “x_fp_hash” value in the merchant's form is invalid, an error
email is sent to the notification email address configured in the interface:

This is a notification that a request for payment failed for the online store Merchant's Store Title.
An error page was displayed to the customer.

Reply to this message or e-mail support@e-xact.com if you have any questions.

The following error was found:

X fp hash could not validate the integrity of the payment from the transaction key, x_fp_hash, x_fp_sequence, x_fp_timestamp, x_amount, and (optionally) x_currency_code values of the request.

10.1.2 Testing the “x_fp_hash” calculation
The Administration Console has a tool to test the merchant's implementation
in the Hosted Checkout section. It allows merchants to inspect the hash
calculated by Hosted Checkout with known inputs. This value can then be quickly and
manually compared with the hash calculated on the merchant's side.

10.1.3 Tying the Payment to a Particular Order
The parameters “x_invoice_num”, “Invoice Number”, and “x_po_num”,
“Purchase Order Number”, are optional fields designed to tie the payment to a
particular order or invoice.

If, for example, the merchant offers a “shopping cart” on their website which
the customer fills with items, the developer will find it convenient to derive a
unique Invoice Number or Purchase Order Number from the shopping cart
identifier in order to track payments for a customer's purchases.

The difference between the two fields is that “x_invoice_num” appears on the
CTR whereas “x_po_num” does not.

Both are returned to the merchant's server with Relay Response and Silent Post.

Also, both fields are truncated to 20 characters. See details in Section 6.3 Order
and Customer Detail Fields

10.2 Relay Response Implementation
When Relay Response is configured, an HTTP POST request is sent to the
configured Relay Response URL. The applicable fields are documented under
Section 7 Relay Response Mode.

10.2.1 Generated HTML
The response generated by the merchant's server to the Relay Response request
is passed on to the customer's web browser without any changes. However as
the page will still have an https://checkout.e-xact.com URL it is important to
make all links to pages or images on the merchant's website absolute.

10.2.2 Customer Cookies
The merchant's website may be tracking the customer with a cookie. This
cookie will not be part of the request sent from E-xact's servers to the
merchant's server with the Relay Response request but the merchant may set a
field in the initial request that has the same values as the cookies.

For example,

Here, two extra parameters, “merchant_cookie_1” and
“merchant_cookie_2”, have been added to the comparable Relay Response
example from Section 9.2 Example Including Relay Response. These
values are sent with the Relay Response request so that the merchant's server
can identify the customer making the payment.

Caution should be used when adding extra keys as in the above example to
avoid duplicate name usage. Either sending a test request or viewing Section 7
can deduce the full list of taken names.

10.2.3 Relay Response Signature
The request generated by E-xact's servers is signed with a cryptographic hash.
The name of the hashed field is “x_MD5_Hash”. It is calculated as the MD5
Hash of the concatenation of the strings:

Payment Page Configuration Relay Response Key
Value of “x_login”
Transaction ID (value of “x_trans_id”)
Amount, exactly two digits after the period ($100 is used as “100.00”)

Note: this calculation is not the same as that of the “x_fp_hash” field.

For example, using the below values:

Field	Value
Relay Response Key	abcdefgh12345
x_login / Payment Page ID	WSP-EXAMPL-01
Transaction ID (field “x_trans_id”)	123456789
Amount	1.00

The MD5 calculation is performed for the string:

abcdefgh12345WSP-EXAMPL-011234567891.00

Resulting in:

0ae500c0cb7d78f9c26598d6456180dd

The key is configured on the Relay Response tab of the Administration
Console.

10.2.4 Sample Relay Response POST
This section shows in detail what is sent to the merchant's server with a relay
response HTTP POST request.

Most merchants will use https so that the POST is encrypted (not shown).

The sample POST is based on a credit card payment. The relay response URL is
(see the x_relay_url value):

http://testmerchant.com/relay_response

POST /relay_response HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Date: Tue, 13 Jan 2009 16:01:41 GMT
Content-Length: 2585
Host: testmerchant.com

SequenceNo=435677&Language=1&Tax2Amount=&x_currency_code=
CAD&x_ship_to_city=&x_method=CC&EXact_Resp_Code=00
&CardHoldersName=Susan+Testname&x_email=test%40yahoo.com&
Authorization_Num=ET141870&MerchantCountry=Canada&
Reference_3=&x_description=&x_amount=564.30&exact_ctr=
%3D%3D%3D%3D%3D%3D%3D%3D+TRANSACTION+RECORD+
%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AMerchant+Plug-in+
Test+Store%0A44+King+Street+West%0AVancouver%2C+BC+V6B+
4X2%0ACanada%0Awww.smwp.com%0ATYPE%3A+Purchase%0A
%0AACCT%3A+Visa++%24564.30+CAD%0A%0ACARD+HOLDER+
%3A+Susan+Testname%0ACARD+NUMBER+%3A+%2A%2A%2A
%2A%2A%2A%2A%2A%2A%2A%2A%2A1111%0AEXPIRY+DATE+
%3A+12%2F12%0ATRANS.+REF.+%3A+1234567%0ADATE%
2FTIME+++%3A+13+Jan+09+16%3A01%3A41%0AREFERENCE+
%23+%3A+435677+305+M%0AAUTHOR.%23++++%3A+ET141870
%0A%0A++++Approved+-+Thank+You+000%0A%0A%0A%3D%3D%
3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D
%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%
3D%3D%3D%3D%3D%0A&x_card_num=&Ecommerce_Flag=0&
x_po_num=&x_city=Vancouver&_response_reason_text=Transaction+
has+been+approved&MerchantName=Merchant+Plug-in+Test+Store&
Bank_Resp_Code_2=&Tax1Number=&x_ship_to_address=&x_type=
AUTH_CAPTURE&Transaction_Approved=YES&Card_Number=%2A%
2A%2A%2A%2A%2A%2A%2A%2A%2A%2A%2A1111&x_duty=
&x_fax=&x_relay_response=TRUE&exact_wsp_version=1.7&
Customer_Ref=&x_invoice_num=1234567&x_relay_url=http%3A
%2F%2Ftestmerchant.com%2Frelay_response&x_cavv_response=
&CAVV_Response=0&Secure_AuthResult=0&x_address=555+A+Street
&x_response_reason_code=1&x_show_form=PAYMENT_FORM
&x_ship_to_country=&Bank_Message=Approved&Tax1Amount=
&x_version=3.1&x_ship_to_company=&Transaction_Error=
false&exact_issconf=&x_test_request=TRUE&SurchargeAmount=
0&x_tax_exempt=&x_phone=&x_merchant_email=&MerchantProvince=
BC&Reference_No=1234567&ZipCode=&x_trans_id=
2150&x_last_name=Testname&x_cvv2_resp_code=&Retrieval_Ref_No=
5669951&Secure_AuthRequired=0&x_zip=The+Zip&
x_response_subcode=S&x_ship_to_zip=&Bank_Resp_Code=000&
CVD_Presence_Ind=0&x_ship_to_last_name=&x_exp_date=&
Client_Email=&exact_issname=&x_fp_sequence=123456&
Transaction_Type=00&x_tax=127.26&x_company=&
MerchantCity=Vancouver&CAVV_Algorithm=0&x_country=Canada&
x_avs_code=&x_first_name=Susan&CVV2=&AVS=&Tax2Number=
&x_ship_to_state=&x_response_code=1&DollarAmount=564.30&
TransactionCardType=VISA&EXact_Message=Transaction+Normal&
Expiry_Date=1212&x_login=WSP-RELAY-80&x_card_code=&
Transaction_Tag=2150&x_ship_to_first_name=&MerchantPostal=
V6B+2K4&Client_IP=&x_freight=15.0&x_cust_id=&commit=
Checkout&MerchantAddress=44+King+Street+West&XID=
&x_MD5_Hash=abfaf1d1df004e3c27d5d2e05929b529&x_state=
BC&x_reference_3=&x_auth_code=ET141870&x_fp_timestamp=1231877695

The values of the above HTTP POST are listed in the table below:

Key	Value
SequenceNo	435677
Language	1
Tax2Amount
x_currency_code	CAD
x_ship_to_city
x_method	CC
EXact_Resp_Code	0
CardHoldersName	Susan Testname
x_email	test@yahoo.com
Authorization_Num	ET141870
MerchantCountry	Canada
Reference_3
x_description
x_amount	5643
exact_ctr	"======== TRANSACTION RECORD ========\r\n\r\nMerchant Plug-in Test Store\r\n44 King Street West\r\n Vancouver, BC V6B 4X2\r\nCanada\r\nwww.smwp.com\r\nTYPE: Purchase \r\n\r\nACCT: Visa $564.30 CAD\r\n\r \nCARD HOLDER : Susan Testname\r \nCARD NUMBER : ************1111 \r\nEXPIRY DATE : 12/12\r\nTRANS. REF. : 1234567\r\nDATE/TIME : 13 Jan 09 16:01:41\r\nREFERENCE # : 435677 305 M\r\nAUTHOR.# : ET141870\r\n\r\n Approved - Thank You 000\r\n\r\n\r\n========================= ==========="
x_card_num
Ecommerce_Flag	0
x_po_num
x_city	Vancouver
x_response_reason_text	Transaction has been approved
MerchantName	Merchant Plug-In Test Store
Bank_Resp_Code_2
Tax1Number
x_ship_to_address
x_type	AUTH_CAPTURE
Transaction_Approved	YES
Card_Number	************1111
x_duty
x_fax
x_relay_response
exact_wsp_version	1.7
Customer_Ref
x_invoice_num	1234567
x_relay_url	http://testmerchant.com/relay_response
x_cavv_response
CAVV_Response	0
Secure_AuthResult	0
x_address	555 A Street
x_response_reason_code	1
x_show_form	PAYMENT_FORM
x_ship_to_country
Bank_Message	Approved
Tax1Amount
x_version	3.1
x_ship_to_company
Transaction_Error	FALSE
exact_issconf
x_test_request	TRUE
SurchargeAmount	0
x_tax_exempt
x_phone
x_merchant_email
MerchantProvince	BC
Reference_No	1234567
ZipCode
x_trans_id	2150
x_last_name	Testname
x_cvv2_resp_code
Retrieval_Ref_no	5669951
Secure_AuthRequired	0
x_zip	The zip code
x_response_subcode	S
x_ship_to_zip
Bank_Resp_Code	0
CVD_Presence_Ind	0
x_ship_to_last_name
x_exp_date
Client_Email
exact_issname
x_fp_sequence	123456
Transaction_Type	0
x_tax	127.26
x_company
MerchantCity	Vancouver
CAVV_Algorithm	0
x_country	Canada
x_avs_code
x_first_name	Susan
CVV2
AVS
Tax2Number
x_reference_3
x_ship_to_state
x_response_code	1
DollarAmount	5643
TransactionCardType	VISA
EXact_Message	Transaction Normal
Expiry_Date	1212
x_login	WSP-RELAY-80
x_card_code
Transaction_Tag	2150
x_ship_to_first_name
MerchantPostal	V6B 2K4
Client_IP
x_freight	15
x_cust_id
commit	Checkout
MerchantAddress	44 King Street West
XID
x_MD5_Hash	abfaf1d1df004e3c27d5d2e05929b529
x_state	BC
x_auth_code	ET141870
x_fp_timestamp	1231877695

10.2.5 Relay Response Sample Code
To the merchant's server, the Relay Response POST looks just like an ordinary
form post where a user fills out a web form then the web server processes the
posted parameters and responds with HTML. However, with Relay Response,
there is no form filled out.

There are also two other differences:
1. URLs occurring in the HTML that is returned should be absolute since the
    page will be shown under an https://checkout.e-xact.com URL and not the
    merchant's.
2. The merchant does not have normal access to the customer's cookies since
    the Hosted Checkout server also does not have access. However, section 10.2.2
    "Customer Cookies" demonstrates how to handle this.

The following samples demonstrate:

- How the parameters related to the state of the transaction are evaluated:

- x_response_code
- x_response_reason_text
- exact_ctr
- exact_issname (INTERAC Online payments only)
- exact_conf (INTERAC Online payments only)

- How to use parameters sent with the original redirect from the merchant's
   website to the Hosted Checkout payment form.

Sample Implementation in JSP
Here is a simple example in JSP, for a successful transaction:



Sample Implementation in Ruby/Rails


Sample Implementation in ASP


Sample Implementation in PHP


-->

11 Customer's Browser
Requirements
The customer browser requirements detailed below are the minimum
prerequisites.

11.1 Cookies
Hosted Checkout requires the customer's browser to have cookies enabled. If
it does not have cookies enabled, the customer will be prompted to enable
them. A “Try Again” link is provided for smooth recovery.

11.2 JavaScript
The pages and forms generated by Hosted Checkout do not depend on JavaScript being
enabled in the customer's browser. Conversely, some banking websites may
require this.

All pages appear the same whether JavaScript is enabled or not.

However, if the customer's browser does not have JavaScript enabled,
automatic redirection to Interac Online is not possible. Thereafter the page
shown in Section 3.4.1 Customer is Redirected to INTERAC Online, will
become visible in the customers browser and the customer will need to click
the “Continue Payment” button.

12 Authorize.net SIM Compatibility
The Hosted Checkout protocol is compatible with the Authorize.net SIM
protocol to ensure that leading shopping carts are supported. For example,
these shopping carts have been tested: Zen Cart, OsCommerce and Comersus.
Refer to the Knowledge Base, http://kb.e-xact.com, for additional notes.

The Authorize.net SIM protocol is described at:

http://www.authorize.net/support/SIM_guide.pdf

In most cases switching to Hosted Checkout will require that only the POST-URL be
changed.

The Authorize.net SIM is aimed primarily at credit card payments. However,
Hosted Checkout allows INTERAC Online payments to be processed
transparently.