Hosted Checkout Payment Pages Integration Manual
- 1 Intended Audience
- 2 Introduction
- 3 Appearance
- 4 Configuration
- 4.1 Payment Page: General Settings
- 4.2 Payment Page: Payment Types Settings
- 4.3 Payment Page: Pay Now/Donate Now Settings
- 4.4 Payment Page: Receipt Page Settings
- 4.5 Payment Page: Receipt Emails Settings
- 4.6 Payment Page: Recurring Settings
- 4.7 Payment Page: Customize Form Settings
- 4.8 Payment Page: Appearance Settings
- 4.9 Payment Page: Security Settings
- 4.10 Payment Page: Hash Calculator
- 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 Soft Descriptor Fields
- 6.5 Unsupported Fields and Unsupported SIM Emulation Functionalities
- 6.6 Dynamic Currency Conversion (DCC)
- 6.7 Dynamic Pricing (DP)
- 6.8 Fees
- 6.9 Visa Checkout
- 6.10 Special Payment
- 6.11 Google Analytics
- 7 Relay Response
- 8 Silent Post
- 9 Transaction Result Fields
- 9.1 Basic Relay Response and Silent Post Fields
- 9.2 Basic Relay Response and Silent Post Fields (Credit Card Only)
- 9.3 Payeezy Gateway Additional Fields
- 9.4 Payeezy Gateway API Response Fields
- 9.5 Payeezy Gateway API Response Fields (Credit Card Only)
- 9.6 Response Reason Codes and Text
- 9.7 Common Bank Response Codes
- 9.8 Address Verification Result Codes
- 9.9 CVV2 Verification Indicator Codes
- 9.10 CVV2 Result Codes
- 10 Example Payment Forms
- 10.1 Basic Example
- 10.2 Example Including Relay Response
- 10.3 Resulting Payment Form
- 10.4 Example with Order Details
- 11 Implementation and Testing Guide
- 11.1 Generation of the Checkout Form
- 11.1.1 Calculating the x_fp_hash value
- 11.1.2 Testing the x_fp_hash calculation
- 11.1.3 Tying the Payment to a Particular Order
- 11.2 Relay Response Implementation
- 11.2.1 Generated HTML
- 11.2.2 Customer Cookies
- 11.2.3 Relay Response Signature
- 11.2.4 Sample Relay Response POST
- 11.2.5 Relay Response Sample Code
1 Intended Audience
This document is intended for
- Merchants who want to understand the payment processing features of the First Data Payeezy Gateway 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 Payeezy Gateway, the payment request parameters that should be sent by the merchant and how they are processed, and includes request examples.
2 Introduction
A Payeezy Gateway Payment Page is a securely hosted web payment form designed to accept Internet-based E-commerce transactions.
With Payment Pages in place a merchant is no longer exposed to the sensitive payment details required to process a payment, because Payment Page redirects the customer from merchant website to a payment form hosted by Payeezy Gateway. Such solution minimizes PCI scope for the merchant and hence only requires completion of the PCI DSS SAQ-A (Self-Assessment Questionnaire A and Attestation of Compliance). Additionally, by using Payment Pages the merchant has access to an expanding toolkit of payment options and other features without the need for additional code development. If for some reason the visual redirect to another website does not fit well with the merchant checkout flow, there is an option to use an iFrame functionality that allows to run the Payeezy Gateway Payment Page within the merchant user interface.
Payeezy Gateway Payment Pages redirect the customer from merchant website to a payment form hosted by Payeezy Gateway. 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.globalgatewaye4.firstdata.com/payment
Please note that Demo accounts should submit transactions to this URL: https://demo.globalgatewaye4.firstdata.com/payment
Within the parameters of this HTML form the merchant specifies the location of the Payeezy Gateway Payment Page along with payment details and authentication information. These are usually implemented as hidden input in the HTML form.
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 Payeezy Gateway merchants.
3 Appearance
The merchant can customize the appearance of their Payeezy Gateway Payment Page as follows:
- All pages can be styled to match the merchant's website design by configuring a color scheme and specifying the logo to be displayed.
- The merchant’s server can be set to render entirely the last page (customer receipt display) through Relay Response - see Section 7 for more information on this topic.
4 Configuration
The Payeezy Gateway 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 Payeezy Gateway Payment Pages's payment form requires the configuration of at least one Payeezy Gateway 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.
Payeezy Gateway Payment Pages are administered through the "Payment Pages" tab in the Payeezy Gateway Real-time Payment Manager (RPM), accessible only to administrators.
Merchants can add as many Payeezy Gateway Payment Pages as required. This allows the support of:
- Multiple shopping carts
- Multiple languages
- Various processing options
- A dedicated demo Payeezy Gateway Payment Page
To add a new Payeezy Gateway Payment Page, click the “Create a New Payment Page” link.
To change an existing Payeezy Gateway Payment Page, click on its Payment Page ID.
Additionally, existing Payeezy Gateway Payment Pages can be previewed or deleted on this tab.
4.1 Payment Page: General Settings
The General section contains settings that are mandatory to First Data Payeezy Gateway Payment Page setup. The remaining sections determine things such as appearance, information and receipt handling, etc. but do not need to be filled in immediately for the Payeezy Gateway Payment Page to be created.
Settings:
- Payment Page Title: this is the label used for the individual payment page.
- "Return to Your Site" URL: after the transaction is completed, the user can be redirected or offered a link to the URL specified here.
- Maximum Number of Payment Attempts: this is a security measure aimed at stopping malicious activity. Customers will have this number of tries (1, 2, or 3) to complete their transaction after which they will be blocked for a period of time.
- Notification Email: the email address specified in this field will receive copies of the payment confirmation emails sent to each customer (if this feature is enabled) as well as alert messages indicating errors returned from the payment page.
Hit "Next" to proceed to the next step, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
4.2 Payment Page: Payment Types Settings
This section defines options including currency and payment options that can be offered to the customer on the First Data Payeezy Gateway Payment Page for both testing and production modes.
Currency
1. Select currency. Note that only one currency per payment page is allowed. The option to select currency will not be displayed if merchant has only one type set up on the account.
Terminal Assignment
If the "Use This Payment Page For All Terminals" option is selected, a Gateway ID value can be supplied in the x_gateway_id form parameter to toggle the terminal this payment is processed with.
Credit Card Payments
1. Select "Enable Credit Card Payments" to offer this option.
2. Select the Merchant account and Terminal to process credit card payments through in Test and Live Processing modes. If no merchant accounts or terminals have been set up, the drop-down menus will not be displayed.
CVV2 Options
Note that this setting only appears if the Terminal selected for Credit Card Payments supports CVV2.
Make CVV2 Input Mandatory - By default, the payment page will display a drop-down list next to the Security Code field, which allows the user to choose a reason for not providing a value. Checking this option removes the drop-down list, thereby making the Security Code value a mandatory field during payment collection.
3-D Secure Settings
These settings are associated with Verified by Visa and MasterCard Securecode. Successful setup of this option requires that the merchant obtain production Verified by Visa and/or Secure code credentials from their merchant bank.
1. Check the Enable 3-D Secure box in order to utilize this feature
2. Check the Require Enrollment box to force customer enrollment in the VbV/Securecode programs in order to complete their transaction
Apple Pay
The terminal used by a Payment Page must be set up to accept this method of payment in order for Apple Pay section to be visible.
Please refer to the following article for further reading about Apple Pay on HCO:
https://support.payeezy.com/hc/en-us/articles/360000634793
TeleCheck
Check the "Enable TeleCheck" box in order to utilize this payment method. The terminal selected must be set up to accept this method of payment in order for this option to appear.
Paypal Enabled
Offering Paypal as a payment option requires:
1. An active Paypal account
2. Enabling Paypal API access in the Paypal account settings
1. Select the "Enable Paypal" box to offer this payment option to customers.
2. Fill in the Paypal API credentials: API login, API password, API signature
For testing PayPal payments, test API credentials (often referred to as "Sandbox credentials") obtainable from PayPal should be used. Information about these credentials can be found here.
Hit "Next" to proceed to the next step, "Previous" to return to the preceding screen, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
4.3 Payment Page: Pay Now/Donate Now Settings
Notes on the use of this feature:
- For additional recommendations, see Fraud Best Practices.
- This form only generates the code required to create buttons and does not allow these settings to be saved
- After making changes to the button settings, the "Refresh" button should be clicked to regenerate the code and appearance preview
- The code generated to create the button is presented in the "Button HTML" area; it is this code that should be copied and added to a web page to show the button
- If it is necessary to only allow a set of specific dollar amounts for payment (eg. $5, $10, $20), a merchant can create multiple buttons and present the appropriate one to the user after the selection has been made by the customer
Amount: By entering an amount here, the generated button will direct to a payment page that specifies this dollar amount and customers will not be given the option to change it. If this box is left empty, customers will instead be presented with the option to input a dollar amount of their choice.
Donation Prompt: In the case where a customer is prompted for a donation, the text entered here will be presented to the customer before they proceed.
Use Relay Response: Enabling this option turns on Relay Response for this button. See this page for more information.
Tracking ID: The text entered here will appear in the transaction details screen in the User ID field in RPM in order to identify the button that was used.
Display Text: The text entered here will be displayed for the button.
Button Width: The number entered here controls the width of the button.
Style: The options here allow the presentment of a normal rectangle shape, or one with rounded edges.
Background Color: The color value entered here will be used in the main body of the button. A color picker tool is available by clicking on the color block itself.
Border Color: The color value entered here will be used for the border of the button. A color picker tool is available by clicking on the color block itself.
Font Color: The color value entered here will be used for the text color of the button. A color picker tool is available by clicking on the color block itself.
Font Size: The size of the button's text can be adjusted here by entering a number measured in pixels.
Font Family/Weight/Style: Font names can be manually entered in this box, and a customer's computer will use them if the font is present on their computer. Fonts can also be selected from a pre-defined list of commonly available fonts. The text can also be given bold weight or be italicized.
Soft Descriptor Settings: The settings here control what soft descriptors will be used by the button. Available options are DBA Name, Merchant Contact Info, Street, City, Region, Postal Code, Country, MID, and MCC Override. For more comprehensive information about soft descriptor usage, please see this page.

4.4 Payment Page: Receipt Page Settings
These settings determine the transaction receipting options. For more information on Relay Response, Silent Post, and Receipt Link click here.
Receipt Page Settings
- Select a Return Link Method:
- AUTO POST
- POST
- AUTO GET
- GET
- LINK
- REDI
- Receipt Link text. This is the hyper-linked text that will display to the customer as the link to return them to the merchant's site. For example, "Return to Mystore".
- Receipt Link URL. This is the URL the customer will click to return to the merchant's website.
- Reference Number Title. If you are using the x_invoice_num value this setting will determine how it is labeled on the First Data Payeezy Gateway Payment Page. For example, "Invoice Number", or "Order ID", etc.
- Customer Reference Title. See Reference Number Title above.
Relay Response Settings
- Allow Relay Response. Check this box if Relay Response is the receipting method chosen.
- Relay Response URL. If Relay Response is allowed, this is URL that Payeezy Gateway Payment Pages will relay transaction results to AND receive HTML back from.
- Allow HTTP Redirect to the Merchant Website. When this option is selected, any HTTP redirect requests Payeezy Gateway Payment Pages receives in the relay response back from the merchant will pass the customer back to the merchant's website - instead of displaying the receipt page on the Payeezy Gateway Payment Pages domain.
- Validate Relay Response HTML. This option will allow Payeezy Gateway Payment Pages to validate the HTML the merchant's servers relay back for the receipt page.
Silent Post Settings
- Silent Post URL. If Silent Post is desired, this is URL that Payment Pages will relay transaction results to. Payeezy Gateway Payment Pages will not "listen" for a response back from this URL.
Hit "Next" to proceed to the next step, "Previous" to return to the preceding screen, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
4.5 Payment Page: Receipt Email Settings
Email Enabled: check this box to send payment confirmation email to customers so they will automatically receive a receipt of their transaction.
"From:" Email: customers receiving payment confirmation emails will get them from this email address.
Receipt Email Header/Footer: use these fields to customize the payment confirmation email. For example, a header may look like: "This is an official receipt" and a footer: "Thank you for your business".
The Header/Footer can be a maximum of 255 characters long and contain plain text.
Hit "Next" to proceed to the next step, "Previous" to return to the preceding screen, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
4.6 Payment Page: Recurring Settings
The Recurring section presents settings for configuring Recurring payments with a First Data Payeezy Gateway Payment Page. Recurring functionality for a Payeezy Gateway 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.
4.7 Payment Page: Customize Form Settings
The settings on this page are used to create custom layout and positioning for the form fields on the Payment Page. These fields can be dragged and dropped in order to change their display order. Additionally, field labels can be renamed or removed by clicking on the text. In case the original field names are lost and need to be redisplayed, the "Reset labels" link can be used. Note that depending on a page's setup, not all fields visible in the screenshot below may be available for every Payment Page.
NOTE: The User Defined Fields correspond to x_user1 (User Defined 1), x_user2 (User Defined 2), and x_user3 (User Defined 3) values accordingly from the HCO Integration guide. These fields, including the x_ref_num (Reference/Order #), are display only fields on your Payment Page. This means that it will display data submitted to the order page but you will not be able to edit/type into the box. In order for this data to be collected from your customer and displayed on your Payment Page, the form on your website that connects to your Payment Page, must collect and send the information to your Payment Page.
Also, note that the following options change how the form on the First Data Payment Page (card information collection page) appears to your customers. This form does not change anything on your own website, or the Pay Now/Donate Now Button.
Form Height: The payment form's height can be restricted to the pixel value entered here.
Form Width: The payment form's width can be restricted to the pixel value entered here.
Custom Text Settings: "Heading Title" and "Button Title" can be modified. If the fields are left blank, a default language is applied.
Here is a screenshot of a payment page after the customization is applied:
4.8 Payment Page: Appearance Settings
Select the preview link to see a preview of the First Data Payeezy Gateway Payment Page, including logos and color choices.
Language Settings: English and Spanish options are available
Header Logo: merchants can choose to keep the existing logo, do not show any logo, or upload a new logo of their choice.
Credit Cards: merchants can change the order that card type icons appear on a Payment Page by dragging and dropping the images shown.
Color and Font Settings: customize the background color, header background color, body text font, body text color, header font, and header font color. Use the name (i.e. black) or the hex-encoded value (i.e. #000000). A color picker is also available and can be activated by clicking on the color wheel.
Mobile Header Logo: A unique logo for Payment Pages optimized for display on mobile devices can be uploaded here.
Mobile Color and Font Settings: customize the background color, header background color, body text font, body text color, header font, and header font color. Use the name (i.e. black) or the hex-encoded value (i.e. #000000). A color picker is also available and can be activated by clicking on the color wheel.
External Style Sheet: Even more appearance options can be used by adding a link to a custom style sheet here. Specific styling options available can be determined by inspecting the HTML used on a Payment Page. Note that whenever possible this link should use HTTPS as some browsers may generate security warnings or not display the style sheet otherwise.
Hit "Next" to proceed to the next step, "Previous" to return to the preceding screen, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
4.9 Payment Page: Security Settings
In this section, the encryption keys for First Data Payeezy Gateway Payment Pages are generated. Note that if the Payeezy Gateway Payment Page is currently in use in either Demo or Production modes, generating new keys will break the existing page links.
Do not regenerate the merchant key unless absolutely certain.
HMAC Calculation
Two types of encryption are offered: HMAC-SHA-1 and HMAC-MD5. New Payment Pages instances will use HMAC-SHA-1.
HMAC-MD5 option is only advised for legacy solutions.
Transaction Key
This key is one of the values used to calculate the value, "x_fp_hash". This x_fp_hash validates that the merchant’s server generated the redirect parameters correctly and serves as verification to Payeezy Gateway Payment Pages that the form was generated by the merchant's server, and not by the customer or a third party.
1. Press the "Generate New Transaction Key" button to produce a new value.
Response Key
This value is specific to the Relay Response method and is one of the values used to calculate the value, "x_SHA1_Hash" ("x_MD5_Hash" if MD5 was selected in Payment Page Settings). This "x_SHA1_Hash" is how the Payment Pages system cryptographically signs transaction results returned to the merchant's server. Merchants can calculate and use the x_SHA1_Hash to verify that these results are being returned from Payment Pages and not an unknown third party.
1. Press the "Generate New Response Key" button to produce a new value.
Hit "Next" to proceed to the next step, "Previous" to return to the preceding screen, "Save Changes" to return at a later time or "Cancel" if editing an existing page.
Prevent Payment Page from loading in other websites
When "Prevent Clickjacking" is checked, iFrame Busting is enabled. The feature prevents the Payment Page from loading inside of an iFrame, preventing it form being used on other sites. Please keep in mind that only one of "3DS" or "Prevent Clickjacking" can be enabled at a time.
Note: Clickjacking is enabled by default; if you plan to use an iFrame, please uncheck the option. Not all browsers respond in the same way when the “Prevent Clickjacking” option is active. Some browsers display a blank page, while others do not.
4.10 Payment Page: Hash Calculator
This section contains the hash calculation tool which can be used by developers to compare their figuring of the x_fp_hash value with First Data Payeezy Gateway Payment Pages' derivation.
Note that the values, "x_login", and "Transaction Key" are automatically pre-populated.
1. Enter the following values:
"x_fp_sequence"
"x_fp_timestamp"
"x_amount"
"x_currency_code" (optional)
2. Press the "Generate Hash" button.
The result will appear in the text box beside "Hash (x_fp_hash)".
Compare this result value with that calculated by the merchant's Payment Pages code.
Hit "Previous" to return to the preceding screen.
5 Character Encoding
Incoming parameters should be encoded in UTF-8, except where noted as ASCII, to ensure correct text display and processing.
6 Payment Form Fields
The merchant interfaces with Payeezy Gateway Payment Pages by displaying an HTML form on a website page that submits a POST request to Payment Pages at https://checkout.globalgatewaye4.firstdata.com/payment. Hidden form fields specify the particulars about the payment. The fields supported by Payeezy Gateway Payment Pages are described in this section. When using a demo account, a POST request should be sent to https://demo.globalgatewaye4.firstdata.com/payment.
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 Payeezy Gateway 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 within Payeezy Gateway Hosted Payment Pages. 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". In addition, if TransArmor Multi-Pay token processing is enabled for the merchant account, TransArmor Multi-Pay tokens will be returned for each submitted transaction. The returned Multi-Pay tokens can be utilized within the Payeezy Gateway Web Service interface to initiate subsequent transactions or as a mechanism to issue voids or credits to the underlying credit card number referenced by the Multi-Pay token. It is important to note that the hosted check out page delivered to the consumer 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-SHA1 (or 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 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. |
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.7.
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 Payeezy Gateway Payment Pages in:
- Notifications to the merchant about errors
- Relay Response / Silent Post / Receipt Link
Name/Area | Validation | Explanation |
Processing Fields | ||
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 Payeezy Gateway Payment Pages 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 Payeezy Gateway 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 Payeezy Gateway 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 Payeezy Gateway 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 Payeezy Gateway 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 Payeezy Gateway 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. |
x_tpp_id | String [6] |
Third-party Processor ID. Left justified/space filled. First Data value assigned to the Third Party Processor. Spaces may be used to reset TPP ID |
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 Payeezy Gateway Payment Pages via:
- Notification emails to the merchant about errors
- Relay Response / Silent Post / Receipt Link
Important Note: To enable Level 3 field support, you must enable the "Level 3 Processing" option on the General tab of your Payeezy Gateway Payment Page or pass this parameter in your request:. You must also enable it on the General Setting tabs during the Payment Pages configuration.
<input name="enable_level3_processing" type="hidden" value="TRUE" />
NOTE: Just enabling Level 3 check box does not automatically allow you to submit Level 3 data. By not having these processing abilities on your account, this will prevent your transcations from settling. You should contact your First Data saleperson to learn more about adding Level 3 processing abilities to your account.
Order Information Fields | Explanation |
x_cust_id |
Not validated. Purchase order or other number used by merchant’s customer to track the order. 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 Payeezy Gateway 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 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 III 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. For further details see Level III API. 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) utilized at the time of pre-authorization will be utilized 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 to 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). |
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, China, 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_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] |
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. Payeezy Gateway 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 Soft Descriptor Fields
The following properties are used to set soft descriptor information for a transaction on a case-by-case basis.
Important Note About Using Soft Descriptors: Dynamic soft descriptors are submitted only at settlement time and are NOT utilized during authorization. As a result, the dynamic nature of the descriptor will not show on a pending authorization statement, but will show on the statement once the transaction has settled. If you would like to use Soft Descriptors, please contact your First Data Relationship Manager or Sales Rep and have them set your "Foreign Indicator" in your "North Merchant Manager File" to "5".
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 |
6.5 Unsupported Fields and Unsupported SIM Emulation Functionalities
The following fields and their corresponding SIM Emulation functionality are not supported by Payeezy Gateway Payment Pages:
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_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”. |
6.6 Dynamic Currency Conversion (DCC)
The standard DCC use case is a where a payment is entered through the HCO, and only through the credit card form. Card numbers are checked for DCC eligibility, if they are not found to be eligible, the transaction is processed as usual. The customer sees no difference.
If the card does qualify, the customer is presented with a "DCC-opt-in" form with two options "Cardholder chooses to pay in own currency" and "Cardholder chooses to pay in ABC," where ABC is the terminal's currency. The former constitutes an Opt-In, the latter constitutes an Opt-Out.
In the Opt-Out case, the transaction is processed as usual.
In the Opt-In case, the customer is presented with a confirmation page, and if they confirm, the transaction is processed as a DCC-Opt-In transaction.
This means that the receipt indicates the exchange rate, the amount in the terminal's currency, and the amount in the customer's local currency. The merchant can also see these fields in the DCC section of transaction details.
For the merchant there are only a few differences when using a payment page with a terminal that has DCC enabled.
- Transaction details in the Transaction Search will have a DCC section at the bottom of the display. Only in the case where the DCC indicator has a value of '1' was a currency conversion actually performed. (A DCC indicator with a value of '2' indicates that the card number presented was not eligible and a DCC indicator value of '3' indicates that the customer has chosen to pay in the terminals or Client's base currency).
- In the Closed Batch Report of the RPM (Real Time Payment Manager), all HCO - DCC transactions, where the customer has opted in, will be included in the DCC/DP Total amount for the terminal.
- Under the Transaction Search option, when searching by Currency, DCC Opt-In transactions in that foreign currency are included.
- The relay response/silent post (if configured and used) will include the extra fields when the payment was made with either a Visa or MasterCard.
dcc_indicator
: one of 1,2,3
If the dcc_indicator is a 1 or 3:
dcc_foreign_amount
dcc_foreign_currency_code
dcc_exchange_rate
dcc_margin_rate
dcc_exchange_rate_source
If the HCO is used for Pre-Authorizations, and the merchant completes a DCC Opt-In payment through the Transaction Search or API, the current exchange rate will be automatically obtained and applied.
When refunding DCC-Opt-In transactions, through either the Transaction Search or the API, the customer will be refunded in their card's currency, the prevailing exchange rate will be automatically obtained.
To read more about how Dynamic Currency Conversion functions please click here to view the Payeezy Gateway Dynamic Currency Conversion and Dynamic Pricing Reference Guide.
Important: If the currency of the transaction request is different from the terminal's, any DCC data will be ignored.
6.7 Dynamic Pricing (DP)
The general DP use case is when the merchant obtains an exchange rate for a given currency (as chosen by the customer), then shows all prices in their shopping cart or Ecommerce site in that selected currency.
The merchant includes a reference to the exchange rate record in their redirect to the HCO, as well as the total amount in both the terminal's base currency and the foreign currency.
These total amounts and the foreign currency are verified against the exchange rate in the exchange rate record.
Note: Dynamic Pricing can only be conducted on Visa and MasterCard cards. To learn more about how this feature functions please view the DCC/DP Feature Guide by clicking here.
In order to use the HCO with DP (Dynamic Pricing), the merchant's web site will perform a Merchant Rate Request with the foreign currency that the customer has chosen.
The response for the rate request will include the exchange rate and the rate response identifier is to be used as shown below.
This merchant rate will have a field, valid_until
, which indicates for how long the rate will remain valid.
When redirecting the customer to the HCO, the following 2 additional fields must be included:
* x_dp_rate_response_id
* x_dp_foreign_currency_amount
The x_fp_hash
value is computed with a different string compared to non-DP HCO:
x_login^x_fp_sequence^x_fp_timestamp^x_amount^x_dp_foreign_currency_amount^x_currency_code^x_dp_rate_response_id |
Note: The fields, "x_dp_foreign_currency_amount"
and "x_dp_rate_response_id"
are to be included in the Hash Calculation as well.
Example:
Field Name |
Sample Value |
---|---|
x_login |
WSP-FDATA-10 |
x_fp_sequence |
123456 |
x_fp_timestamp |
1424480303 |
x_amount |
12.24 |
x_foreign_currency_amount |
1210.0 |
x_currency_code |
USD |
x_dp_rate_response_id |
2-620aff334cbd3f3ede6c64722bbef295971b986a488f07e6b1c47dbcf8802eb6 |
Then the hash will be computed on
WSP-FDATA- 10 ^ 123456 ^ 1424480303 ^ 12.24 ^ 1210.0 ^USD^ 2 -620aff334cbd3f3ede6c64722bbef295971b986a488f07e6b1c47dbcf8802eb6 |
These are the valid values for x_fp_hash
Hash Algorithm |
Valid x_fp_hash Value |
---|---|
SHA-1 |
9cf265e3f67095b9f8ff4da3a4e1c83fca02a439 |
MD5 |
83b2586a388579ada6e9fe6d1de2a5c9 |
Important notes:
- The
x_currency_code
parameter is required for DP / HCO. - The
x_currency_code
parameter must be equal the terminal's currency code. - The foreign currency amount will be validated against the amount multiplied by the exchange rate of the merchant rate obtained under 1.
- The exchange rate response must be valid for at least 15 minutes from the time the customer is sent to HCO.
To read more about how Dynamic Pricing functions please click here to view the Payeezy Gateway Dynamic Currency Conversion and Dynamic Pricing Reference Guide.
A field indicating “Fee Tag” is an optional field in the HCO. The logic to determine Fee processing will follow the path shown below:
-
If the optional Fee field is populated by the merchant, the associated Fee will be displayed upon the consumer facing HCO payment page as defined by the merchant. This is a Fee override.
-
If the optional Fee field is absent or not populated by the merchant, the defined Fee structure will be applied to the transaction and displayed on the consumer facing HCO payment page. This is the standard Fee model.
Depending upon the transaction mode selected, the Fee will be treated as:
-
Part of the Order Amount following the authorization/completion of the aggregated Order amount
-
Separate from the Order Amount and following a separate and distinct authorization/completion path from the original Order amount.
If the Fee is defined and present, the total Order amount displayed will be determined as the original order amount + the Fee + any other related charges (tax, shipping).
The Fee will be displayed to the consumer via a merchant defined field tag. This tag could represent a “Service Fee”, “Processing Fee”, “Transaction Fee”, etc…. It is up to the merchant to define what the intent of this field is.
The sample below reflects the HCO page Preview, the same update applies to the Mobile page preview if fees are enabled on the Fees tab.
To read more about how Fees function in the Gateway please click here to view the Payeezy Gateway Fees article.
HCO Purchase
As discussed above, selecting the new Visa Checkout radio button and then clicking the Visa Checkout button will bring the cardholder to the Visa Checkout lightbox for authentication.
Clients can then log into the Payeezy Gateway Real-time Payment Manager to search for any transactions. Clicking on a particular transaction provides full detail (below) including whether the transaction was performed via Visa Checkout and the assigned Visa Checkout Call ID (transaction ID).
HCO Purchase (search/reports)
HCO Preauthorization (search/reports)
Transaction details indicate whether the transaction was a Purchase or a Pre-Authorization (which is followed by a Pre-Authorization Completion when the merchant fulfills the order).
HCO - Voiding a VCO transaction in the RPM
In “Actions” click on “Void” (marked in red on the screenshot)
The following screen with void transaction will be presented.
HCO - Refunding HCO transaction in the RPM
In “Actions” click on “Refund” (marked in red on the screenshot)
The following screen with refund transaction will be presented.
To learn about Special Payment, please refer to the feature article Special Payment.
To enable Special Payment in HCO, there is a need to pass an HCO flag x_special_payment. From a card-holder perspective, there is no visual difference between a regular card transaction and a Special Payment transaction.
Field | Explanation |
x_special_payment |
To enable Special Payment, pass x_special_payment="B" as an HCO parameter (Any other value will be ignored; in such case the transaction will be processed as a regular card transaction) |
To learn about Google Analytics for Payment Pages, please refer to the feature article Google Analytics for Payment Pages.
Field | Explanation |
x_ga_tracking_id |
Use this field to pass Tracking ID from Google Analytics
|
7 Relay Response
This method involves an HTTP request <-> response between Payeezy Gateway and merchant server, at the end of which Payeezy Gateway relays the response content to the customer. The steps are:
- Payeezy Gateway makes an HTTP POST request containing the transaction results to the merchant server (see Section 9, "Transaction Result Fields" for details on the data that would be sent).
- The merchant sever responds back with HTML content
- Payeezy Gateway 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 Payeezy Gateway.
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 Payeezy Gateway displays the standard transaction receipt to the customer. This is fallback behavior so it is important to note that Payeezy Gateway is expecting a response from the merchant.
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:
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 Payeezy Gateway Payment Pages interface. If empty, the URL from the Payeezy Gateway Payment Pages interface is used. |
8 Silent Post
This option is enabled by adding a “Silent Post URL” to the “Receipt Page” tab of the Payeezy Gateway 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 Payeezy Gateway, 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.
If you are getting an error email regarding silent post failing, please check the following:
1) You are accepting and responding to the silent post with HTTP 200 (This is the only accepted HTTP response)
2) Ensure no redirect information/headers are being sent (this is a server to server request)
9 Transaction Result Fields
There are four different categories of fields of which the first three are covered in the following tables:
- Basic Relay Response and Silent Post “x_” parameters.
- Payeezy Gateway Payment Pages Relay Response fields.
- Most of the response fields returned for the equivalent Payeezy Gateway web service API request.
- Most of the POST parameters from the initial request from the merchant's website to the Payeezy Gateway Payment Pages payment form. This includes, x_login, x_amount etc.
9.1 Basic Relay Response and Silent Post Fields
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, generated by Payeezy Gateway. |
x_SHA1_Hash | SHA1 Hash | SHA1 Hash, in hexadecimal, of the concatenation of these strings:
|
x_MD5_Hash (for legacy implementations only; please migrate to usage of SHA1) |
MD5 Hash | MD5 Hash, in hexadecimal, of the concatenation of these strings:
|
9.2 Basic Relay Response and Silent Post Fields (Credit Card Only)
Field | Description | Explanation |
x_avs_code | Address Verification Result Code | See table under Section 9.8 Address Verification Result Codes |
x_cvv2_resp_code | CVV2 Response Code | See table under Section 9.9 CVV2 Verification Indicator Codes |
x_cavv_response | CAVV Response Code | Not supported. Field is empty. |
9.3 Payeezy Gateway Additional Fields
Field | Description | Explanation |
exact_wsp_version | WSP Protocol Version | Latest value 1.7 |
exact_ctr | Receipt | Payeezy Gateway generated Customer Transaction Record (CTR) |
9.4 Payeezy Gateway API Response Fields
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 9.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" tab. |
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 this page 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 |
MerchantAddress | Merchant's Address | This and the following Merchant fields are taken from the Payeezy Gateway record of the merchant / account information provided during account provisioning. This information is also visible in Payeezy Gateway Real-time Payment Manager (RPM) on the Home page. |
MerchantCity | Merchant's City | See above |
MerchantCountry | Merchant's Country | See above |
MerchantName | Merchant's Account Name | See above |
MerchantPostal | Merchant's Postal Code | See above |
MerchantProvince | Merchant's Province | See above |
MerchantURL | Merchant's URL | See above |
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 Payeezy Gateway and passed through to the financial institution |
TransactionCardType | Payment Type |
The type of credit card, possible values are:
|
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 values as x_trans_id. |
Expiry_Date |
Card expiry date |
Indicates the expiry date of the card processed in MMYY format |
9.5 Payeezy Gateway API Response Fields (Credit Card Only)
Field | Description | Explanation |
AVS | Address Verification Result | See table under Section 9.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 9.9, "CVV2 Verification Indicator Codes" |
CVV2 | Authentication Code returned by the bank | See table under Section 9.10, "CVV2 Result Codes" |
CardHoldersName | Customer's Name | Up to 30 characters |
Card_Number | The credit card number |
This value contains the masked card number unless the TransArmor Multi-Pay token functionality is enabled, in which case a TransArmor Multi-Pay token will be returned. This TransArmor Multi-Pay token value along with the TransactionCardType and expiration date can be used within the Payeezy Gateway Web Service API to initiate another transaction for the originating card number. In the test account environment the TransArmor token is returned as random numberswith the last 4 digits the same as the card number. In the production environment the token is returned as only random numbers with the last 4 digits the same as the card number. Review Section 3.4 TransArmor Transactions within the Web Service API Integration Guide if you are interested in this functionality. |
Ecommerce_Flag | Payer Authorization Result | "5" if the cardholder was fully authorized by 3-D Secure/Verified by Visa or "6" if the cardholder chose not to participate. If a custom value was passed, it will be returned here unless it was overridden. |
Retrieval_Ref_No | AVS related | The reference number returned with an AVS result |
XID | 3-D Secure Field | 3-D Secure/Verified by Visa value returned by Cardinal Commerce. |
ZipCode | Customer address field | Used for qualifying transactions. |
9.6 Response Reason Codes and Text
The fields below are the Response Reason Codes supported by Payment Pages.
Response Reason Code | Response Reason Text |
1 | Transaction has been approved |
2 | Transaction has been declined |
3 | An error occurred while processing the transaction |
9.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 |
9.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 |
E | AVS Error |
G | Card issuer does not support AVS |
N | No match on address and ZIP/Postal Code |
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 |
Q | Bill to address did not pass edit checks |
D | International street address and postal code match |
B | International street address match, postal code not verified due to incompatible formats |
C | International street address and postal code not verified due to incompatible formats |
P | International postal code match, street address not verified due to incompatible format |
1 | Cardholder name matches |
2 | Cardholder name, billing address, and postal code match |
3 | Cardholder name and billing postal code match |
4 | Cardholder name and billing address match |
5 | Cardholder name incorrect, billing address and postal code match |
6 | Cardholder name incorrect, billing postal code matches |
7 | Cardholder name incorrect, billing address matches |
8 | Cardholder name, billing address, and postal code are all incorrect |
9.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 |
9.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 |
10 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.
10.1 Basic Example
This basic example only specifies the Payeezy Gateway Payment Page record to use, x_login, and the amount to charge, x_amount.
<form action="https://checkout.globalgatewaye4.firstdata.com/payment" method="post">
<input name="x_login" value="WSPEXA00101" 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" type="submit">
</form>
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 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-SHA1 (or HMAC-MD5) from the Transaction Key of the Payeezy Gateway 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”.
10.2 Example Including Relay Response
This basic example enables relay response:
<form action="https://checkout.globalgatewaye4.firstdata.com/payment" method="post">
<input name="x_login" value="WSPEXA00101" 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" type="submit">
</form>
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 Payeezy Gateway 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 Payeezy Gateway Payment Page in the Payeezy Gateway Payment Pages interface.
10.3 Resulting Payment Form
For the two examples in Sections 10.1 and 10.2 the payment form presented to the customer will appear as below. Colors and title may be customized.
10.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 Payeezy Gateway 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.globalgatewaye4.firstdata.com/payment" method="post">
<input name="x_login" value="WSPEXA00101" 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" 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">
</form>
Note:
- 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:
11 Implementation and Testing Guide
This Section deals with resources provided by First Data that the merchant's web developer can utilize for implementation and testing.
11.1 Generation of the Checkout Form
The main Payment Pages interface, displayed after a Payeezy Gateway Payment Page is configured, is reached via a checkout form on the merchant's website which posts to the Payment Pages URL at https://checkout.globalgatewaye4.firstdata.com/payment. Section 11 lists some examples for the required HTML code. Note that demo accounts should use the URL https://demo.globalgatewaye4.firstdata.com/payment.
11.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 Payeezy Gateway Payment Pages.
The x_fp_hash calculation is performed using the HMAC-SHA1 key (the Transaction Key from the Payment Page configuration) and the HMAC-SHA1 message, or payload, as the concatenation of x_login, x_fp_sequence, x_fp_timestamp, x_amount, and (if used) x_currency_code and x_fee_amount – 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 Payeezy Gateway Payment Page configuration as seen in the image below. (HMAC-MD5 is used for legacy implementations, if selected)
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 C, C#, Python, Ocami, and Coldfusion are available here.
For example, using the values in the table below:
Field | Value |
x_login | WSP-GOODS-70 |
x_fp_sequence | 123454321 |
x_fp_timestamp | 1228953556 |
x_amount | 100.00 |
Transaction Key | AL81Li7D4laXYDtpfgO_lInQ |
the resulting HMAC-MD5 is calculated with the payload of
WSP-GOODS-70^123454321^1228953556^100.00^
and has this value
2dba76cedb7847547fd964fc903e9f2c
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.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.
11.1.2 Testing the x_fp_hash calculation
The Payeezy Gateway 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 Payeezy Gateway Payment Pages with known inputs. This value can then be quickly and manually compared with the hash calculated on the merchant's side.
11.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".
11.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 underSection 8, "Relay Response".
11.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.globalgatewaye4.firstdata.com URL it is important to make all links to pages or images on the merchant's website absolute.
11.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 the Payeezy Gateway 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.globalgatewaye4.firstdata.com/payment" method="post">
<input name="x_login" value="WSPEXA00101" 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" type="submit">
<input name="merchant_cookie_1" value="12345" type="hidden">
<input name="merchant_cookie_2" value="67890" type="hidden">
</form>
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 7.
11.2.3 Relay Response Signature
The request generated by the Payeezy Gateway servers is signed with a cryptographic hash. The name of the hashed field is x_SHA1_Hash (x_MD5_Hash for legacy implementation). It is calculated as the SHA1 Hash of the concatenation of the strings:
- 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:
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 SHA1 calculation is performed for the string:
abcdefgh12345WSP-EXAMPL-011234567891.00
Resulting in:
0ae500c0cb7d78f9c26598d6456180dd
The key is configured under the "Security" tab of the Payment Pages interface.
11.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):
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.test.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&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_CAP
TURE&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_Re
f=&x_invoice_num=1234567&x_relay_url=http%3A%2F%2Ftestmerchant.com
%2Frelay_response&x_cavv_response=&CAVV_Response=0&x_addre
ss=555+A+Street&x_response_reason_code=1&x_show_form=PAYMENT_FORM&x_ship_to_co
untry=&Bank_Message=Approved&Tax1Amount=&x_version=3.1&x_ship_to_company=&Tran
saction_Error=false&exact_issconf=TRUE&SurchargeAmount=0&x_tax
_exempt=&x_phone=&x_merchant_email=&MerchantProvince=BC&Reference_No=1234567&Z
ipCode=&x_trans_id=2150&x_last_name=Testname&x_cvv2_resp_code=&Retrieval_Ref_N
o=5669951&x_zip=The+Zip&x_response_subcode=S&x_ship_to_z
ip=&Bank_Resp_Code=000&CVD_Presence_Ind=0&x_ship_to_last_name=&x_exp_date=&Cli
ent_Email=&exact_issname=&x_fp_sequence=123456&Transaction_Type=00&x_tax=127.2
6&x_company=&MerchantCity=Vancouver&CAVV_Algorithm=0&x_country=Canada&x_avs_co
de=&x_first_name=Susan&CVV2=&AVS=&Tax2Number=&x_ship_to_state=&x_response_code
=1&DollarAmount=564.30&TransactionCardType=VISA&EXact_Message=Transaction+Norm
al&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+Ki
ng+Street+West&XID=&x_MD5_Hash=abfaf1d1df004e3c27d5d2e05929b529&x_state=BC&x_r
eference_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-inTest Store\r\n44 King Street West\r\n Vancouver, BC V6B 4X2\r\nCanada\r\nwww.test.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 : 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_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 |
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 | |
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 |
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 |
11.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:
- URLs occurring in the HTML that is returned should be absolute, since the page will be shown under a https://checkout.globalgatewaye4.firstdata.com URL and not the merchant's.
- The merchant does not have normal access to the payer's cookies, since the Payeezy Gateway Payment Pages server does not have them either, and cannot send them along as cookies. However, Section 11.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"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Receipt</title>
<script type="text/javascript" src="http://merchant.com/javascript.js" ></script>
<link rel="stylesheet" href="http://merchant.com/style.css" type="text/css" />
</head>
<html>
<body>
<h1>Merchant.com Online Store</h1>
<h2>Thanks for your order</h2>
<p>
Your order was processed successfully. Here is your receipt.
Your order will be shipped in two business days.
</p>
<pre>
<%=request.getParameter("exact_ctr")%>
</pre>
<% if(request.getParameter("exact_issname") != null) { %>
<p>
Issuer: <%=request.getParameter("exact_issname")%>
Confirmation Number: <%=request.getParameter("exact_issconf")%>
</p>
<% } %>
<p>
<% String track_url = "http://merchant.com/order_tracking/" + request.getParameter("x_invoice_num"); %>
You can track it at <a href="<%= track_url%>"><%= track_url %></a>.
</p>
<p>
Return to <a href="http://merchant.com/home">home</a>.
</p>
</body>
</html>
Some more samples can be found in the Sample Code area which demonstrate:
- How the parameters related to the state of the transaction are evaluated:
- x_response_code
- x_response_reason_text
- exact_ctr
- How to use parameters sent with the original redirect from the merchant's website to the Payeezy Gateway Payment Pages payment form.