Hosted Payment Page Integration Guide

Field

Value

Description

x_login

Varies by merchant and payment page

Maximum length 20, the Payment Page ID from the Exact Payment Pages interface. 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

Equal to or greater than 0

Total dollar amount to be charged inclusive of freight and tax; Maximum Length 15.

Zero dollar Authorizations can be performed: Typically this is done in scenarios where the card details need to be verified and tokenized, but not charged immediately. Performing this type of transaction can be done by submitting "0" as the dollar amount and submitting "x_type" as "AUTH_ONLY". 

Note that in the aforementioned case the hosted checkout page presented to the cardholder will not include the dollar amount. Instead of a "Pay With Your Credit Card" button, the consumer will see a "Submit" button.

x_fp_hash

String

HMAC-SHA256 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.

This field must be lower case.

x_show_form

PAYMENT_FORM

Case-sensitive.

Name/Area

Validation

Description

x_type

AUTH_CAPTURE / AUTH_ONLY

The type of the transaction.

AUTH_CAPTURE is Purchase/Sale.

AUTH_ONLY known as Authorization / Preauthorization

ORDER will invoke a PayPal order transaction; other payment methods will not be displayed to the cardholder.

x_gateway_id

Gateway ID

If the Payment Page is set up to use all terminals, this value must be populated with the Gateway ID of the desired terminal.

Receipt Page Fields

x_receipt_link_method

LINK / GET / POST / AUTO-GET / AUTO-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. 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_url

Valid URL

Target of hyperlinked text or action for HTML GET/POST. If empty, or invalid URL, the default value from the Payment Pages interface is taken.

Fields Common to Payment Collection 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 Payment Pages interface is taken.

x_color_background

HTML color name or hex code

Background color 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_customer

TRUE / FALSE

Should a confirmation email be sent to the customer; default is set in the Payment Pages interface.

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 "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_code

Currency Code

Currency of the transaction. Case sensitive.

Recurring Billing Fields

x_recurring_billing

TRUE / FALSE

To enable Recurring functionality through Payment Pages, this must be set to TRUE

x_recurring_billing_id

Plan identifier

HCO Plan ID (retrievable by viewing a Recurring plan in the administrative interface)

x_recurring_billing_amount

Positive number

The amount that will be billed each time a Recurring payment is run

x_recurring_billing_start_date

YYYY-MM-DD

Optional; sets a custom start date for Recurring payments (otherwise it will be inherited from the Plan default)

x_recurring_billing_end_date

YYYY-MM-DD

Optional; sets a custom end date for Recurring payments (otherwise it will be inherited from the Plan default)

Ecommerce_flag

Positive number

The value passed in this flag can be used to classify the type of payment being performed. Possible values are outlined here.

Order Information Fields

Description

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

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

x_customer_tax_id

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

x_line_item

This parameter may occur several times (with different items). The item details are displayed on the Payment Page 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 Title<|>Item Description<|>Quantity<|>Unit Price<|>Taxable (Y or N)<|>Product Code<|>Commodity Code<|>Unit of Measure<|>Tax Rate<|>Tax Type<|>Tax Amount<|>Discount Indicator<|>Discount Amount<|>Line Item Total

For Level 3 to qualify, the above fields are Required: Item Description, Quantity, Product Code,Commodity Code, Unit Price, Unit of Measure, Tax Amount, Discount Amount, and Line Item Total.

The size limit for Item ID, Item Name, Item Description, Item Quantity is 255 characters each. There is a limit of 99 line items for a single transaction. 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

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.

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

For two stage transactions (pre-auth/completion), the reference number (x_po_num) at the time of pre-authorization will be used at time of transaction completion. An override of this value is not supported. The consistent usage of values enables a merchant to achieve the best interchange rates and least re-authorizations. Typically, the reference number field is the purchase order number or unique sequence value associated with a given transaction suite.

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.

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

Required Character Format is ASCII.

Customer Name and Billing Address Fields

x_first_name

For billing address Required Character Format is ASCII.

Max. Field Length: [30] - (First & Last Name Combined)

x_last_name

For billing address Required Character Format is ASCII.

Max. Field Length: [30] - (First & Last Name Combined)

x_company

For billing address Required Character Format is ASCII.

Max. Field Length: [30]

x_address

For billing address

Max. Field Length: [28] (longer length will lead to a rejection of the transaction)

x_city

For billing address Required Character Format is ASCII.

Max. Field Length: [20]

x_state

For billing address; Must be submitted as full name ie: Georgia, Maryland, Quebec

Max. Field Length: [2]

x_zip

For billing address

Max. Field Length: [10]

x_country

For billing address; Must be submitted as full name ie: United States, Canada

Max. Field Length: [2]

x_phone

For billing address

Max. Field Length: [14]

x_fax

For billing address

Max. Field Length: [14]

Customer Shipping Address Fields

x_ship_to_first_name

For shipping address Required Character Format is ASCII.

x_ship_to_last_name

For shipping address Required Character Format is ASCII.

x_ship_to_company

For shipping address Required Character Format is ASCII.

x_ship_to_address

For shipping address

x_ship_to_city

For shipping address Required Character Format is ASCII.

x_ship_to_state

For shipping address; Must be submitted as two letter code. e.g. CA, TX.

x_ship_to_zip

For shipping address

x_ship_to_country

For shipping address; Must be submitted as two letter code. e.g. US

Additional Customer Data Field

x_customer_ip

IP address of the customer.

Max. Field Length: [15]

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.

Max. Field Length: [30]

Level 3 Fields

x_tax

Non-negative Number. The tax in dollars. (Required for Level III qualification)

Max. Field Length: [12]

x_tax_exempt

TRUE / FALSE

x_freight

Non-negative Number. Freight charge in dollars. (Required for Level III qualification)

Max. Field Length: [12]

x_duty

Non-negative Number. Duty in dollars. (Required for Level III qualification)

Max. Field Length: [12]

alternate_tax

Non-negative Number. The alternate tax in dollars.

Max. Field Length: [9]

discount_amount

Non-negative Number. The total discount amount applied to a transaction. (Required for Level III qualification)

Max. Field Length: [12]

tax_rate

Non-negative Number. Submitted as a percentage value (ie. 12)

Max. Field Length: [4]

x_fee_amount

Equal to or greater than 0 Total fee amount in dollars to be charged; Maximum Length 15. This is added to x_amount to produce total charged. Specifying x_fee_amount overrides any amount calculated by the fees configuration for terminal. Ignored if fees are not enabled for terminal.

Max. Field Length: [15]

Field

Comment

x_sd_dba_name

Business name

Required Character Format is ASCII.

x_sd_merchant_contact_info

Business contact information

Required Character Format is ASCII.

x_sd_street

Business street

x_sd_city

Business city

Required Character Format is ASCII.

x_sd_region

Business region

Required Character Format is ASCII.

x_sd_country_code

Business country

x_sd_postal_code

Business postal/zip code

x_sd_mid

Business MID number

x_sd_mcc

Business MCC number

Field

Explanation

x_ga_tracking_id   

Use this field to pass Tracking ID from Google Analytics

Field

Value

Description/Comment

x_relay_response

TRUE

Required for Relay Response. Case sensitive (FALSE is not allowed)

x_relay_url

Payment Pages Configuration

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

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 9.6 Response Reason Codes and Text, below.

x_response_reason_text

Response Reason Text

See table under Section 9.6 Response Reason Codes and Text, below.

x_auth_code

Approval Code

Authorization number of the transaction

x_trans_id

Transaction ID

Unique identifier

x_SHA1_Hash

SHA1 Hash

SHA1 Hash, in hexadecimal, of the concatenation of these strings:

• Relay Response Key
• x_login
• Transaction ID (field x_trans_id)
• Amount, two digits after the period ($100 is used as “100.00”)

exact_ctr

Receipt

Exact Payments generated Customer Transaction Record (CTR)

x_payment_id  

Payment ID

Used to make subsequent transactions through the API