Hosted Checkout Integration Manual

Created by Richard Moore, Modified on Fri, 15 Mar 2024 at 11:22 AM by Anna Byazina

1 Intended Audience

This document is intended for

  • Merchants who want to understand the payment processing features of E-xact Transactions' Payment Pages service.
  • Web developers who integrate a merchant's website with Payment Pages for payment processing.

This document covers the configuration of the merchant's account at E-xact, the payment request parameters that should be sent by the merchant and how they are processed, and includes request examples.

2 Introduction

A Payment Page is a securely hosted web payment form designed to accept Internet-based E-commerce transactions.

With Payment Pages customers can pay with their credit cards or directly from their bank account through Interac Online. Interac Online 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 Payment Pages. Once authenticated the customer is returned to the Payment Page where the process is completed and a receipt is displayed to them.

With Payment Pages 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 toolkit of payment options and fraud prevention tools without the need for additional development.

Payment Pages redirect the customer to a payment form hosted by E-xact Transactions. 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:

If you're using an account on our demo system, you'll want to use this URL instead:

Within the parameters of this HTML form the merchant specifies the location of the Payment Page along with payment details and authentication information. These are usually implemented as hidden input in the HTML form. Note that there is a 7000 byte limit on the data sent in the POST request.

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 form are configured through an online management interface available to all E-xact merchants.

3 Appearance

The merchant can customize the appearance of their Payment 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. If further Payment Page customization is required, a link (absolute URLs only) to a CSS file can be entered into the field marked "CSS URL". All Payment Page elements can be customized.

  3. The merchant’s server can be set to render entirely the last page (customer receipt display) through Relay Response - see Section 8 for more information on this topic.

4 Configuration

The Payment Pages configuration determines how each payment is processed. This configuration covers payment processing presentation and functionality such as Relay Response and email notification.

The redirect to Payment Pages'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", for more information.

Payment Pages are administered through the "Payment Pages" tab, accessible only to administrators. An individual Payment Page view presents you with several options to control the payment form:

  • General Settings
  • Payment Types Settings
  • Receipt Page Settings
  • Receipt Emails Settings
  • Appearance Settings
  • Security Settings
  • Hash Calculator


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 “Create a 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 Payment Page: General Settings

The “General” tab of a Payment Page defines the title and location of the Payment Page.


The "Return to Your Site URL" is used for the “Return to WSP Example Shop” link that can be viewed in the image here. It is also used for timeout pages allowing the customer to return to the merchant's website.

You may also set "Maximum Number of Payment Attempts" to prevent customers from submitting payment information more than the designated amount of times.

The notification email setting is used to determine where copies of payment notification emails to customers are sent, and where any Payment Pages error messages are sent.

4.2 Payment Page: Payment Types Settings

The payment processing terminal options can be set in the Payment Types tab.


The "Currency" setting determines what currency will be used for the current Payment Page. If you'd like to offer multiple currencies on your site, you'll want to set up separate Payment Pages for each currency offering.

Processing Mode determines whether this Payment Page is being used in "live" or "test" mode.

To offer Credit Card processing, enable the "Enable Credit Card Payments" checkbox. To offer Interac Online processing, enable the "Enable Interac Payments" checkbox. To offer PayPal processing, enable the "Enable PayPal" checkbox. If you're not offering credit card payments, you may check the "Bypass the first page when customers checkout" option which will skip the page shown in here.

Select the desired merchant/terminal combinations under the Sections "Test Processing" and "Live Processing" for both the Interac and Credit Card payment types.

For PayPal payments, you will need to supply a PayPal certificate or the PayPal API login, password, and signature values. The PayPal experience can be customized by choosing the PayPal layout for mobile devices, regular browsers, or by having PayPal automatically detect between the two.

Payments may be processed in test or live mode. This option may be preconfigured (as shown here) depending on terminal settings. In the sample account shown there are no live processing terminals available, therefore that option is not displayed. Test mode can also be triggered with the redirect parameter x_test_request; see Section 6.2, "Transaction and Display Fields".

Note: When a payment request is made in test mode the “Pay from your Bank Account” button on the Payment Page form will not redirect to the Interac Online site, but to a page hosted by E-xact that simulates an Interac Online payment. For testing PayPal payments, test API credentials obtainable from PayPal should be used.

If you would like to enable 3-D Secure (Verified by Visa/Mastercard SecureCode) for your Payment Page, activate the "Enable 3-D Secure" checkbox. Note that registration is required to take advantage of this feature. If you want to force customers who haven't enrolled in this program to do so before being permitted to complete payment, you'll also want to enable the "Require Enrollment" checkbox.

4.3 Payment Page: Receipt Page Settings

The receipt page settings determine how receipts are displayed to customers, and how transaction data is handled after a transaction has been completed.


On this page, you're presented with several Return Link methods: GET, AUTO-GET, POST, AUTO-POST, LINK, and REDI. The following is a breakdown of the different methods offered and their uses.

User-Initiated Navigation

These methods add a link or button to the standard transaction receipt that is displayed to the customer.  Their actions are triggered only if the customer clicks the link or button.

  • LINK - The configured Receipt Link is embedded as a simple HTML link. No transaction results are sent when the customer clicks this link.

  • GET - The configured Receipt Link is embedded as the submit button of an HTML form (method GET).  When the customer clicks this button the transaction results are sent as HTTP GET parameters (URL query string).

  • POST - The configured Receipt Link is embedded as the submit button of an HTML form (method POST). When the customer clicks this button the transaction results are sent as HTTP POST parameters.

The transaction results sent is a subset of the fields described in Section 10, "Transaction Result Fields".  Specifically, this subset does not include the E-xact API Response Fields listed in Section 10.4 and Section 10.5.

Automatic Navigation

These methods do not display the standard transaction receipt to the customer.  Instead, the customer's browser automatically submits an HTTP form to the configured Receipt Link and is up to the merchant server hosting the Receipt Link website to generate and display the transaction receipt to the customer.

  • AUTO-GET - Sends the transaction results (same subset as method GET) as HTTP GET parameters (URL query string).

  • AUTO-POST - Sends the transaction results (full set described in Section 10, "Transaction Result Fields") as HTTP POST parameters.

  • REDI - Submits the HTTP form with method GET, sending the transaction results as HTTP GET parameters (URL query string). This method is obsolete and will be phased out eventually.

The "Reference Number Title" field can be used to display an invoice identifier on the Payment Page. Leave this value empty if you do not want it displayed on the Payment Page. Note that this value can also be set on a case-by-case basis by using the "x_invoice_num" form field.

Likewise, the "Customer Reference Title" field can be used to display a customer identifier. Again, this value can be set by using the form field "x_po_num".

Enable the "Allow Relay Response" setting if you would like to use this method for your receipt handling. More information on this topic can be found in Section 8.

If Relay Response and Receipt Link methods are both enabled, Relay Response will take precedence so the receipt page generated by the merchant server would be displayed.  E-xact's standard transaction receipt page with the configured Receipt Link would only be displayed if there is a communication failure with the merchant's server for Relay Response.

Note: The following options listed are not visible in the screenshot above

Check the "Allow HTTP Redirect to Merchant Website" option if you would like to send the customer back to the merchant website using an HTTP redirect while using Relay Response. 

The "Validate Relay Response HTML" option will perform a check on the HTML returned from the merchant server to ensure that it has not been tampered with. More information on this feature can be found here.

By filling out the "Silent POST URL" field, transaction results will be sent back to the merchant server via a HTTP POST request to the specified URL, but E-xact's servers will not expect a response. This method can be used alongside the Relay Response and Receipt Link methods, typically as an extra measure of redundancy to ensure that transaction results make it back to the merchant server. More information on this subject can be found in Section 9.

4.4 Payment Page: Receipt Emails Settings

If you would like customers to receive a confirmation email of their transaction, you can enable the "Send a payment confirmation email to customers". The email "From" address can also be specified on this page, so that emails appear to be coming from the merchant site. The notification email header and footer can also be set on this page for additional customization.


4.5 Payment Page: Appearance Settings

The appearance of a Payment Page is configured in the Appearance tab where the language, logo, and background and text colours can be set.


4.6 Payment Page: Security Settings

On this page you'll find information and settings used to validate the security of transactions.


The "Encryption Type" setting determines what encryption method is use to calculate the Transaction Key and Response Key. It is recommended that MD5 encryption is used, though SHA-1 encryption may be used for custom applications.

The "Transaction Key" and "Response Key" values are both found on this page, and can be re-generated if required. Note that if these keys are changed, any Payment Pages that have been set up with the old keys will no longer function until they're updated with the new keys.

4.6.1 Security Settings: reCAPTCHA

The E-xact Gateway now provides reCAPTCHA functionality on all Hosted Checkout Payment Pages. This feature helps to mitigate attacks on merchant payment pages from bots and scripts. As of December 3rd, 2020, reCAPTCHA has been enabled by default on all newly created payment pages.

Fig. 1 - reCAPTCHA: cardholder interaction

reCAPTCHA is optional for Hosted Payment Pages; it can be toggled on or off under the Payment Pages "Security" tab.


Fig. 2 - reCAPTCHA: checkbox enablement under "Security"

4.7 Payment Page: Hash Calculator


The Hash Calculator is a tool that can be used to ensure that the "x_fp_hash" value of a transaction is being generated properly on the merchant side. Transaction values can be entered here so that the actual hash value can be compared with the expected result. This is typically only used in debugging scenarios when the hash value isn't being generated correctly and a way is needed to identify the incorrect transaction variable(s) that are throwing off the hash calculation.

4.8 Payment Page: Recurring

The Recurring section presents settings for configuring Recurring payments with a Payment Page. Recurring functionality for a Payment Page can be enabled or disabled here, and the customer agreement text presented to customers can be set. The agreement text can be formatted using Markdown.


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 Payment Pages by displaying an HTML form on a website page that submits a POST request to Payment Pages at Hidden form fields specify the particulars about the payment. The fields supported by Payment Pages 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.

x_loginVaries by merchantMaximum length 20, the Payment Page ID from the Payment Pages interface. Case-sensitive.
x_fp_sequenceChosen by merchantCan 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.
x_fp_timestampTime in seconds since January 1, 1970. UTC, Coordinated Universal TimeRequests expire after 15 minutes / 900 seconds.
x_amountNumberTotal dollar amount to be charged inclusive of freight and tax; Maximum Length 15.
x_fp_hashStringHMAC-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 even if x_currency_code is not present a ^ character is still added. The transaction key can be found in the "Security" tab when viewing the settings for a specific Payment Page.


  • 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.6.
  • The x_show_form parameter is required in order to stay compatible with the protocol. See this page for more information on 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 Payment Pages in:

  • Notifications to the merchant about errors
  • Relay Response / Silent Post / Receipt Link

Processing Fields  
x_test_requestTRUE / FALSEOptional: Process payment in test mode. Case-sensitive.

The type of the transaction.

AUTH_CAPTURE is Purchase/Sale.

AUTH_ONLY known as Authorization/Pre-authorization. Amount must be greater than $0.00.

AUTH_TOKEN is a Pre-authorization transaction that returns a transaction tag which can be used by the API to perform additional transactions for that cardholder. Amount can be $0.00 or greater.

PURCHASE_TOKEN will capture funds and return a transaction tag which can be used by the API to perform additional transactions for that cardholder. 

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_methodLINK / GET / POST / AUTO-GET / AUTO-POSTSpecifies the type of link made back to the merchant's website. Case-sensitive.
x_receipt_link_textAny textHyperlinked text or submit button value.  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 Payment Pages interface.
x_receipt_link_urlValid URLTarget of hyperlinked text or action for HTML GET/POST. If empty or not a valid URL, the default value from the Payment Pages interface is taken.
Fields Common to Payment Collection and Receipt Page  
x_logo_urlValid URLDisplayed on header of Payment Form and Receipt Page. If empty or not a valid URL, the default value from the Payment Pages interface is taken.
x_color_backgroundHTML colour name or hex codeBackground colour of the Payment Form and Receipt Page. If empty or invalid, default value from the Payment Pages interface is used.
Email Setting Fields  
x_email_customerTRUE / FALSEShould a confirmation email be sent to the customer; default is set in the Payment Pages interface.
x_merchant_emailValid email addressEmail 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 "General" section of the Payment Pages interface. No email will be sent to this address if it does not meet standard email format checks.
Transaction Data Fields  
x_currency_codeUSD / CADCurrency of the transaction. Case sensitive. (Interac Online supports only CAD)
Recurring Billing Fields  
x_recurring_billingTRUE / FALSETo enable Recurring functionality through Payment Pages, this must be set to TRUE
x_recurring_billing_idPlan identifierHCO Plan ID (retrievable by viewing a Recurring plan in the administrative interface)
x_recurring_billing_amountPositive numberThe amount that will be billed each time a Recurring payment is run
x_recurring_billing_start_dateYYYY-MM-DDOptional; sets a custom start date for Recurring payments (otherwise it will be inherited from the Plan default)
x_recurring_billing_end_dateYYYY-MM-DDOptional; sets a custom end date for Recurring payments (otherwise it will be inherited from the Plan default)

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 Payment Pages via:

  • Notification emails to the merchant about errors
  • Relay Response / Silent Post / Receipt Link

Order Information FieldsExplanation
x_cust_idNot validated. Unique identifier for the customer associated with the transaction.  Not displayed to the customer

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).

NOTE: this field may only contain the following special characters for Interac Online transactions, otherwise an error will be returned and the transasction will not be processed: #$.,-/=?@'.

The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

x_customer_tax_idNot validated. Tax ID of the customer. Not displayed to the customer.

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

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)<|>

The size limit for Item ID, Item Name, Item Description, Item Quantity is 255 characters each. Additionally, the product of Item Quantity multiplied by Item Price must be in the range between -1,000,000,000 and 1,000,000,000


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.

The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

x_descriptionNot validated. Description of the transaction. Not displayed to the customer.

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.

The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

Customer Name and Billing Address Fields 
x_first_nameFor billing address
x_last_nameFor billing address
x_companyFor billing address
x_addressFor billing address
x_cityFor billing address
x_stateFor billing address
x_zipFor billing address
x_countryFor billing address
x_phoneFor billing address
x_faxFor billing address
Customer Shipping Address Fields 
x_ship_to_first_nameFor shipping address
x_ship_to_last_nameFor shipping address
x_ship_to_companyFor shipping address
x_ship_to_addressFor shipping address
x_ship_to_cityFor shipping address
x_ship_to_stateFor shipping address
x_ship_to_zipFor shipping address
x_ship_to_countryFor shipping address
Additional Customer Data Field 
x_customer_ipIP address of the customer.
x_emailEmail 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_taxNon-negative Number. The tax in dollars.
x_tax_exemptTRUE / FALSE
x_freightNon-negative Number. Freight charge in dollars.
x_dutyNon-negative Number. Duty in dollars.


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. Payment Pages perform 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 Functionalities

The following fields and their corresponding functionality are not supported by Payment Pages:

x_header_html_payment_formIgnored, not validated
x_footer_html_payment_formIgnored, not validated
x_header_html_receiptIgnored, not validated
x_footer_html_receiptIgnored, not validated
x_bank_aba_codeFlagged as an error, if present and not “NO”.
x_bank_acct_typeFlagged as an error, if present and not “NO”.
x_bank_nameFlagged as an error, if present and not “NO”.
x_echeck_typeFlagged as an error, if present and not “NO”.
x_card_numFlagged as an error, if present and not “NO”.
x_exp_dateFlagged as an error, if present and not “NO”.
x_card_codeFlagged as an error, if present and not “NO”.
x_trans_idFlagged as an error, if present and not “NO”.
x_auth_codeFlagged as an error, if present and not “NO”.
x_authentication_indicatorFlagged as an error, if present and not “NO”.
x_cardholder_authentication_valueFlagged as an error, if present and not “NO”.
x_duplicate_windowFlagged as an error, if present and not “NO”.

7 Google Analytics

Google Analytics is now available to all merchants using Hosted Checkout payment pages (HCO). Google Analytics can be used to generate metrics relating to your customers’ visits to checkout pages. To use Google Analytics merchants will first need to sign up for the service through Google; that can be done here:

When sending a transaction request to E-xact, merchants can include the following parameters:


Simply pass the token(s) that Google provides as part of your standard request:

 e.g. x_ga_tracking_id = UA-12345-67

The linker parameter can be sent in the same way:

e.g. x_ga_link_domain =

Note: You can view the Google Analytics script on your Payment Page by right clicking and selecting “View Source”, or “Inspect” (the code will appear at the bottom of the HTML body).

8 Relay Response

This method involves an HTTP request <-> response between E-xact and merchant server, at the end of which E-xact relays the response content to the customer. The steps are:

  1. E-xact makes an HTTP POST request containing the transaction results to the merchant server (see Section 10, "Transaction Result Fields" for details on the data that would be sent).
  2. The merchant server responds back with HTML content
  3. E-xact displays the response content to the customer

Step 1 allows the merchant to receive transaction results in real time, which can then be used to update databases, inventory, empty shopping carts, etc.

Step 2 lets the merchant return a customized receipt via the HTML response they return to E-xact.

The merchant server response should be in HTML format, and is passed on to the customer's browser for final display.  If the merchant server response is not received within 25 seconds in Step 2, in Step 3 E-xact displays the standard transaction receipt to the customer.  This is fallback behavior so it is important to note that E-xact is expecting a response from the merchant.

Any resources linked to on the target Relay Response page should use absolute URLs, otherwise they will not load.

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.

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

x_relay_responseTRUERequired for Relay Response. Case sensitive (FALSE is not allowed)
x_relay_urlPayment Pages ConfigurationOptional. The URL to which the gateway posts the response. Validated with the value configured in the Payment Pages interface. If empty, the URL from the Payment Pages interface is used.

9 Silent Post

This option is enabled by adding a “Silent Post URL” to the “Receipt Page” tab of the Payment Pages interface.

Silent Post performs the same Step 1 as Relay Response, sending the same transaction result fields.  But in Step 2, the HTML content (if any) in the merchant server's response is ignored by E-xact, and the flow of action ends here.

Note: there is no guarantee of sequence - for example if both Silent Post and Relay Response are enabled, the merchant server cannot assume the data will always arrive first from Silent Post or vice versa.

10 Transaction Result Fields

There are four different categories of fields of which the first three are covered in the following tables:

  1. Standard “x_” parameters.
  2. E-xact Payment Pages Relay Response fields.
  3. Most of the response fields returned for the equivalent Transaction Processing API request.
  4. Most of the POST parameters from the initial request from the merchant's website to the Payment Pages payment form. This includes, x_login, x_amount etc.

10.1 Standard Fields

The fields below apply to both Interac Online payments and credit card payments.

x_response_codeResponse code

1 for “Approved”

2 for “Transaction was processed, but was not approved”

3 for “Transaction was not processed due to an error”
Typically happens in the case of a Non-Funded Interac Transaction or a cancelled Paypal Transaction

x_response_subcodeResponse SubcodeInternal value. Future use.
x_response_reason_codeResponse Reason CodeSee table under Section 10.6 Response Reason Codes and Text, below.
x_response_reason_textResponse Reason TextSee table under Section 10.6 Response Reason Codes and Text, below.
x_auth_codeApproval CodeAuthorization number of the transaction
x_trans_idTransaction IdUnique identifier, generated by E-xact Transactions. 
x_MD5_HashMD5 HashMD5 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”)

10.2 Standard Fields (Credit Card Only)

The fields below do not apply to Interac Online payments and will be empty in this case.

x_avs_codeAddress Verification Result CodeSee table under Section 10.8Address Verification Result Codes
x_cvv2_resp_codeCVV2 Response CodeSee table under Section 10.9CVV2 Verification Indicator Codes
x_cavv_responseCAVV Response CodeNot supported. Field is empty.

10.3 E-xact Additional Fields

exact_wsp_versionWSP Protocol VersionLatest value 1.7
exact_ctrReceiptE-xact generated Customer Transaction Record (CTR)
exact_issnameIssuer NameThe name of the customer's bank. The merchant is required by Interac to display this field to the customer.
exact_issconfIssuer Confirmation NumberThe confirmation number generated by the customer's bank. The merchant is required by Interac to display this field to the customer.

10.4 E-xact API Response Fields

The fields below apply to both Interac Online payments and credit card payments.

Authorization_NumAuthorization numberThe authorization number returned by the financial institution. 
Bank_MessageDescribes the Bank_Resp_codeMessage provided by the financial institution.
Bank_Resp_code2 or 3 digit codeSee table under Section 10.7, "Common Bank Response Codes". 
Bank_Resp_code_22 digit codeA secondary response returned by the financial institution.
CardHoldersNameCustomer's nameUp to 30 characters. This name will also appear under the Administration Console's "Transaction" 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_EmailEmail Address as provided by customer(Not passed on to the financial institution.)
Customer_RefMerchant DefinedThe value of x_po_num as passed in from the merchant's website 
DollarAmountThe amount of the transactionThe amount of the transaction in dollars and cents.
Exact_MessageMessage about the Processing statusAccompanies the Exact_Resp_code field
Exact_Resp_codeProcessing StatusThe processing status of the transaction. Please refer to this page for further information. The Transaction_Errorproperty will be “True” if this property is not “00”. 
LanguageLanguage of the CTR0 for English, 4 for French
MerchantAddressMerchant's AddressThis and the following Merchant fields are taken from E-xact's record of the merchant / account information provided during account provisioning.  This information is also visible in RPM on the Home page.
MerchantCityMerchant's CitySee above
MerchantCountryMerchant's CountrySee above
MerchantNameMerchant's Account NameSee above
MerchantPostalMerchant's Postal CodeSee above
MerchantProvinceMerchant's ProvinceSee above
MerchantURLMerchant's URLSee above
Reference_NoMerchant DefinedThe value of x_invoice_numas passed in from the merchant's website
SequenceNoSequence NumberSequentially incremented number generated by E-xact and passed through to the financial institution
TransactionCardTypePayment Type

The type of credit card, possible values are:

  • VISA
  • JCB
  • Unknown

The values for Interac Online payments is:

  • Interac Online Debit

Transaction_ApprovedFlag indicating transaction approvalIndicates that the bank approved a transaction and there are no pending errors.
Transaction_ErrorError flagIndicates that there was an error during the processing of the transaction. Values are "true" or "false".
Transaction_TagTag of the transactionIdentifier for the tagged transaction. Same values as x_trans_id.

10.5 E-xact API Response Fields (Credit Card Only)

The fields below do not apply to and will be empty for Interac Online transactions.

AVSAddress Verification ResultSee table under Section 10.8, "Address Verification Result Codes"
CAVVCardholder Authentication Verification ValueValue returned by the Access Control Server to indicate that a cardholder has been validated
CAVV_AlgorithmMethod used to calculate CAVVSent in authorization request.
CAVV_ResponseValidity of the CAVV value providedNot supported
CVD_Presence_IndHow the CVV2 value is handledSee table under Section 10.9, "CVV2 Verification Indicator Codes"
CVV2Authentication Code returned by the bankSee table under Section 10.10, "CVV2 Result Codes"
CardHoldersNameCustomer's NameUp to 30 characters
Card_NumberThe credit card numberThis value is masked
Retrieval_Ref_NoAVS relatedThe reference number returned with an AVS result
Secure_AuthRequired3-D Secure FieldIndicates the status of a 3-D Secure transaction. Used for internal audit.
Secure_AuthResult3-D Secure FieldIndicates the status of a 3-D Secure transaction. Used for internal audit.
ZipCodeCustomer address fieldUsed for qualifying transactions.

10.6 Response Reason Codes and Text

The fields below are the Response Reason Codes supported by Payment Pages.

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

10.7 Common Bank Response Codes

The codes below appear in the field Bank_Resp_Code.

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

10.8 Address Verification Result Codes

The values below occur in the fields AVS and x_avs_response.

AAddress matches but ZIP/Postal code does not
BAddress not provided
EAVS Error
GCard issuer does not support AVS
NNo match on address and ZIP/Postal Code
PAVS does not apply to the transaction
RSystem unavailable - Retry
SCard issuer does not support AVS
UNo address available
W9 digit ZIP/Postal Code match, address does not
XAddress and 9 digit ZIP/Postal Code match

10.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.

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

10.10 CVV2 Result Codes

The values below occur in the fields CVV2 and x_cvv2_resp_code.

NNo Match
PNot Processed
SShould have been provided
UIssuer unable to process request

Example Payment Forms

Below are a few examples of the form placed on the merchant's website that will redirect the customer to the payment form. 

11.1 Basic Example

This basic example only specifies the Payment Page record to use, x_login, and the amount to charge, x_amount.

<form action="https://checkout.e­" method="post"> 
  <input name="x_login" value="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input value="Checkout with E­" type="submit">


  • 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 used 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”.

11.2 Example Including Relay Response

This basic example enables relay response:

<form action="https://checkout.e­" method="post"> 
  <input name="x_login" value="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input name="x_relay_response" value="TRUE" type="hidden">
  <input value="Checkout with E-­" type="submit">

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

<input name="x_relay_response" value="TRUE" type="hidden">

Finally, the Payment Page corresponding to the x_login value needs to have the "Allow Relay Response" checkbox enabled and the "Relay Response URL" field completed in the "Receipt Page" section when viewing an individual Payment Page in the Payment Pages interface.

11.3 Resulting Payment Form

For the two examples in Sections 11.1 and 11.2 the payment form presented to the customer will appear as below. Colours and title may be customized. Whether the credit card, Interac, and PayPal forms appear is controlled by the Payment Page configuration.


11.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 Payment Pages with the independent parameters x_line_item, x_freight, x_duty, and x_tax. For instance, the example below uses x_line_item, x_freight, and x_tax, but not x_duty:

<form action="https://checkout.e-­" method="post"> 
  <input name="x_login" value="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="558.49" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input value="Checkout with E­" type="submit">
  <input name="x_tax" value="26.59" type="hidden">
  <input name="x_freight" value="45.0" type="hidden">
  <input name="x_line_item" value="10<|>1999 Cabernet Sauvignon, 0.7 l<|>1999 Cabernet Sauvignon, 0.7 l <|>10<|>19.95<|>YES" type="hidden"> 
<input name="x_line_item" value="12<|>2003 Merlot, 0.7 l<|>2003 Merlot, 0.7 l<|>12<|>23.95<|>YES" type="hidden">


  • The x_line_item parameter may be repeated. Each occurrence corresponds 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.

For this example form, the resulting payment form will be presented as shown below:


12 Implementation and Testing Guide

If a merchant is not using an SIM compatible shopping cart package, some web development will be required. This Section deals with resources provided by E-xact that the merchant's web developer can utilize for implementation and testing.

12.1 Generation of the Checkout Form

The main Payment Pages interface, displayed after a Payment Page is configured, is reached via a checkout form on the merchant's website which posts to the Payment Pages URL at Section 11 lists some examples for the required HTML code.

12.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 Payment Pages.

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 “Security” tab of the Payment Page configuration as seen in the image below.


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

Example implementations of this calculation in many programming languages including PHP, Java, Python and Perl are available here.

For example, using the values in the table below:

Transaction KeyAL81Li7D4laXYDtpfgO_lInQ

the resulting HMAC-MD5 is calculated with the payload of


and has this value


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 set in the "General" tab of Payment Page configuration:

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­ 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.

The customer will see an error page and and be unable to complete the payment.

12.1.2 Testing the x_fp_hash calculation

The Payment Pages interface has a tool to test the merchant's implementation in the "Hash Calculator" Section. It allows merchants to inspect the hash calculated by Payment Pages with known inputs. This value can then be quickly and manually compared with the hash calculated on the merchant's side.


12.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_numdoes 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".

12.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 8, "Relay Response".

12.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 URL it is important to make all links to pages or images on the merchant's website absolute.

12.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. However, the merchant may set a field in the initial request that has the same values as the merchant's cookies.

For example:

<form action="https://checkout.e-­" method="post"> 
  <input name="x_login" value="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input name="x_relay_response" value="TRUE" type="hidden">
  <input value="Checkout with E­" type="submit">
  <input name="merchant_cookie_1" value="12345" type="hidden">
  <input name="merchant_cookie_2" value="67890" type="hidden">

Here, two extra parameters, merchant_cookie_1 and merchant_cookie_2, have been added to the comparable Relay Response example from Section 11.2, "Example Including Relay Response". These values will then be 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 parameters as in the above example to avoid existing parameter names. The full list of parameter names in use can be taken from a test request, or looked up in Section 8.

12.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 for the x_fp_hash field.

For example, using the below values:

Relay Response Keyabcdefgh12345
x_login / Payment Page IDWSP-EXAMPL-01
Transaction ID (field x_trans_id)123456789

The MD5 calculation is performed for the string:


Resulting in:


The key is configured under the "Security" tab of the Payment Pages interface.


12.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, sent to the hypothetical relay response URL (see the x_relay_url value):

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


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

CardHoldersNameSusan Testname
x_email[email protected]
exact_ctr"======== TRANSACTION RECORD ========\r\n\r\nMerchant Plug-inTest Store\r\n44 King Street West\r\n
Vancouver, BC V6B 4X2\r\nCanada\r\\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 : 13Jan 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_response_reason_textTransaction has been approved
MerchantNameMerchant Plug-In Test Store
x_address555 A Street
x_zipThe zip code
EXact_MessageTransaction Normal
MerchantPostalV6B 2K4
MerchantAddress44 King Street West

12.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, and the web server processes the posted parameters then responds with HTML. Except with Relay Response, there is no form that was 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 a URL and not the merchant's.
  2. The merchant does not have normal access to the payer's cookies, since the Payment Pages server does not have them either, and cannot send them along as cookies. However, Section 12.2.2, "Customer Cookies", shows how to handle this.

Here is a simple example in JSP that covers the scenario of a successful transaction:

<%@ page language="java" import="java.lang.*" %>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"" >
<html xmlns="" lang="en" xml:lang="en">
<script type="text/javascript" src="" ></script>
<link rel="stylesheet" href="" type="text/css" />

<h1> Online Store</h1>

<h2>Thanks for your order</h2>

Your order was processed successfully. Here is your receipt.
Your order will be shipped in two business days.

<% if(request.getParameter("exact_issname") != null) { %>
Issuer: <%=request.getParameter("exact_issname")%>
Confirmation Number: <%=request.getParameter("exact_issconf")%>
<% } %>

<% String track_url = "" + request.getParameter("x_invoice_num"); %>
You can track it at <a href="<%= track_url%>"><%= track_url %></a>.

Return to <a href="">home</a>.

Some more samples can be found in the Code Integration Samples area which 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_issconf (Interac Online payments only)

  • How to use parameters sent with the original redirect from the merchant's website to the Payment Pages payment form.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article