Forums/Hosted Payment Pages

First Data Global Gateway e4℠ Hosted Payment Pages Integration Manual

First Data Support (LL)
posted this on April 08, 2013 01:58

1 Intended Audience

This document is intended for

  • Merchants who want to understand the payment processing features of the First Data Global Gateway e4℠ 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 Global Gateway e4℠, the payment request parameters that should be sent by the merchant and how they are processed, and includes request examples.

2 Introduction

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

With Global Gateway e4℠ Payment Pages in place a merchant is no longer exposed to the sensitive payment details required to process a payment. Additionally, the merchant has access to an expanding toolkit of payment options and fraud prevention tools without the need for additional development.

Global Gateway e4℠ Payment Pages redirect the customer to a payment form hosted by Global Gateway e4℠. 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

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 Global Gateway e4℠ 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 Global Gateway e4℠ merchants.

3 Appearance

The merchant can customize the appearance of their Global Gateway e4℠ Payment Page as follows:

  1. All pages can be styled to match the merchant's website design by configuring a color scheme and specifying the logo to be displayed.
  2. The merchant’s server can be set to render entirely the last page (customer receipt display) through Relay Response - see Section 7 for more information on this topic.

4 Configuration

The Global Gateway e4℠ 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 Global Gateway e4℠ Payment Page's payment form requires the configuration of at least one Global Gateway e4℠ 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.

Global Gateway e4℠ Payment Pages are administered through the "Payment Pages" tab in the Global Gateway e4℠ Real-time Payment Manager (RPM), accessible only to administrators. An individual Payment Page view presents you with several options to control the payment form:

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

Merchants can add as many Global Gateway e4℠ Payment Pages as required. This allows the support of:

  • Multiple shopping carts
  • Multiple languages
  • Various processing options
  • A dedicated demo Global Gateway e4℠ Payment Page

To add a new Global Gateway e4℠ Payment Page, click the “Create a New Payment Page” link.

To change an existing Global Gateway e4℠ Payment Page, click on its Payment Page ID.

Additionally, existing Global Gateway e4℠ Payment Pages can be previewed or deleted on this tab.

4.1 Payment Page: General Settings

The “General” tab of a Global Gateway e4℠ Payment Page defines the title and location of the Global Gateway e4℠ Payment Page.

generaltab.png

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

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

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

The Level 3 Processing setting allows merchants to submit more detailed information about their order with their requests. See Section 6.3 for more information on Level 3 fields.

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.

 

4.2 Payment Page: Payment Types Settings

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

paymentTypes.png

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

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

To offer Credit Card processing, enable the "Enable Credit Card Payments" checkbox.

To offer PayPal processing, enable the “Enable PayPal” checkbox. PayPal transactions can be submitted either as a pre-authorization or as an immediate purchase. Note that PayPal pre-authorizations will expire after 29 days.

To make CVV2 input mandatory for credit card payments, enable “Make CVV2 Input Mandatory”. This option will disable the drop-down box with options to disregard the CVV code and instead will require that it is entered as shown below.

ccvvmand.pngcvvopt.png

Mandatory CVV (left) vs. Optional CVV (right)

Select the desired merchant/terminal combinations under the Sections "Test Processing" and "Live Processing".

For PayPal payments, you will need to supply a PayPal certificate or the PayPal API login, password, and signature values. The PayPal experience can be customized by choosing the PayPal layout for mobile devices, regular browsers, or by having PayPal automatically detect between the two. For testing PayPal payments, test API credentials (often referred to as "Sandbox credentials") obtainable from PayPal should be used. If you do not currently have Paypal credentials, click on the link that says "Create a Paypal Merchant Account" and follow the directions on the Paypal site. Information about these credentials can be found here.

Payments may be processed in test or live mode. This option may be preconfigured depending on terminal settings. Test mode can also be triggered with the redirect parameter x_test_request; see Section 6.2, "Transaction and Display Fields".

To use 3-D Secure on your Payment Page, obtain your credentials from your First Data Boarding representative. Once 3-D Secure has been set up, you will see a "3-D Secure" tab added to the Payment Types page. From this tab select the checkbox, "Enable 3-D Secure".

Select the "Require Enrollment" box to disallow payments with MasterCard or Visa that have not been enrolled. 

If the "Require Enrollment" box is NOT checked, payments with non-enrolled cards, and payments that encounter errors during the 3-D Secure process, will proceed as normal.

Telecheck Settings

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

4.3 Payment Page: Pay Now/Donate Now Settings

The "Pay Now"/"Donate Now" page allows merchants to create customizable one-click checkout buttons that can be embedded on web pages, allowing customers to make a payment quickly and easily.

Notes on the use of this feature:

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

donate.png

4.4 Payment Page: Receipt Page Settings

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

receiptpagetab.png

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

User-Initiated Navigation

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

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

The transaction results sent is a subset of the fields described in Section 9, "Transaction Result Fields".  Specifically, this subset does not include the First Data Global Gateway e4℠ web service API Response Fields listed in Section 9.4 and Section 9.5.

Automatic Navigation

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

  • AUTO-GET - Sends the transaction results (same subset as method GET) as HTTP GET parameters (URL query string).
  • AUTO-POST - Sends the transaction results (full set described in Section 9, "Transaction Result Fields") as HTTP POST parameters.
  • REDI - Submits the HTTP form with method GET, sending the transaction results as HTTP GET parameters (URL query string). This method is obsolete and will be phased out eventually.

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

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

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

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

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

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

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

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

4.5 Payment Page: Receipt Email Settings

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

receiptemailstab.png

4.6 Payment Page: Recurring Settings

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

recurringtab.png

 

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.

 

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

 

NOTE: The User Defined Fields correspond to x_user1, x_user2, and x_user3 values accordingly from the HCO Integration guide.

4.8 Payment Page: Appearance Settings

Select the preview link to see a preview of the First Data Global Gateway e4℠ 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.

appearance.png

 

4.9 Payment Page: Security Settings

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

securitytab.png

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

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

4.10 Payment Page: Hash Calculator

hashtab.png

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

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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 e4 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 e4 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-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 Global Gateway e4℠ 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.
  • The x_show_form parameter is required in order to stay compatible with the Authorize.net protocol. See this page for more information on Authorize.net SIM compatibility.

6.2 Transaction and Display Fields

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

  • The customer's browser will display an error page and the merchant will be notified by email
  • A default value will be substituted

The parameters are passed on as received by Global Gateway e4℠ Payment Pages in:

  • Notifications to the merchant about errors
  • Relay Response / Silent Post / Receipt Link
Name/Area Validation Explanation
Processing Fields    
x_test_request TRUE / FALSE Process payment in test mode. Case-sensitive.
x_type

AUTH_CAPTURE / AUTH_ONLY / AUTH_TOKEN / PURCHASE_TOKEN /ORDER

The type of the transaction.

AUTH_CAPTURE is Purchase/Sale.

AUTH_ONLY known as Authorization / Preauthorization 

AUTH_TOKEN is a Pre-authorization transaction that returns a transaction token which can be used by the API. 

PURCHASE_TOKEN will capture funds and return a transaction token which can be used by the API.

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

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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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.

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 Global Gateway e4℠ 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 Global Gateway e4℠ Payment Page or pass this parameter in your request:

<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 Global Gateway e4℠ 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 

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

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. 
x_last_name For billing address  Required Character Format is ASCII. 
x_company For billing address  Required Character Format is ASCII. 
x_address For billing address
x_city For billing address  Required Character Format is ASCII. 
x_state For billing address; Must be submitted as full name ie: Georgia, Maryland, Quebec
x_zip For billing address
x_country For billing address; Must be submitted as full name ie: United States, China, Canada
x_phone For billing address
x_fax For billing address
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 full name ie: Georgia, Maryland, Quebec
x_ship_to_zip For shipping address
x_ship_to_country For shipping address; Must be submitted as full name ie: United States, China, Canada
Additional Customer Data Field  
x_customer_ip IP address of the customer.
x_email Email address to which the customer's copy of the confirmation email is sent. No email will be sent if the email address does not meet standard email format checks.
Level 3 Fields  
x_tax Non-negative Number. The tax in dollars. (Required for Level III qualification)
x_tax_exempt TRUE / FALSE
x_freight Non-negative Number. Freight charge in dollars. (Required for Level III qualification)
x_duty Non-negative Number. Duty in dollars. (Required for Level III qualification)
alternate_tax Non-negative Number. The alternate tax in dollars.
discount_amount Non-negative Number. The total discount amount applied to a transaction. (Required for Level III qualification)
tax_rate Non-negative Number. Submitted as a percentage value (ie. 12)

 

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. Global Gateway e4℠ 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 Authorize.net Functionalities

The following fields and their corresponding Authorize.net functionality are not supported by Global Gateway e4℠ 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”.

7 Relay Response

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

  1. Global Gateway e4℠ 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).
  2. The merchant sever responds back with HTML content
  3. Global Gateway e4℠ 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 Global Gateway e4℠.

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 Global Gateway e4℠ displays the standard transaction receipt to the customer.  This is fallback behavior so it is important to note that Global Gateway e4℠ 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 Global Gateway e4℠ Payment Pages interface. If empty, the URL from the Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠, 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.

9 Transaction Result Fields

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

  1. Standard Authorize.net “x_” parameters.
  2. Global Gateway e4℠ Payment Pages Relay Response fields.
  3. Most of the response fields returned for the equivalent Global Gateway e4℠ web service API request.
  4. Most of the POST parameters from the initial request from the merchant's website to the Global Gateway e4℠ Payment Pages payment form. This includes, x_login, x_amount etc.

9.1 Standard Authorize.net 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 Global Gateway e4℠. 
x_MD5_Hash MD5 Hash MD5 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”)

9.2 Standard Authorize.net 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 Global Gateway e4 Additional Fields

Field Description Explanation
exact_wsp_version WSP Protocol Version Latest value 1.7
exact_ctr Receipt Global Gateway e4℠ generated Customer Transaction Record (CTR)

9.4 Global Gateway e4 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 Global Gateway e4℠ record of the merchant / account information provided during account provisioning.  This information is also visible in Global Gateway e4℠ 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 Global Gateway e4℠ and passed through to the financial institution
TransactionCardType Payment Type

The type of credit card, possible values are:

  • VISA
  • MASTERCARD
  • AMERICAN EXPRESS
  • DINERS CLUB
  • DISCOVER
  • JCB
  • Unknown
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.

9.5 Global Gateway e4 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 Global Gateway e4 Web Service API to initiate another transaction for the originating card number.

In the test account environment the TransArmor token is returned as random numbers with 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.3TransArmor 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 incompatable formats
C International street address and postal code not verified due to incompatable formats
P International postal code match, street address not verified due to incompatable 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 Global Gateway e4℠ 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="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input value="Checkout" 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-MD5 from the Transaction Key of the Global Gateway e4℠ 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="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input name="x_relay_response" value="TRUE" type="hidden">
  <input value="Checkout" 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 Global Gateway e4℠ 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 Global Gateway e4℠ Payment Page in the Global Gateway e4℠ 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.

checkout.png

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 Global Gateway e4℠ 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="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="558.49" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input value="Checkout" 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:

detailedcheckout.png

11 Implementation and Testing Guide

If a merchant is not using an Authorize.net SIM compatible shopping cart package, some web development will be required. 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 Global Gateway e4℠ 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 Global Gateway e4℠ Payment Pages.

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

Security.jpg

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 Global Gateway e4℠ 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 Global Gateway e4℠ Payment Pages with known inputs. This value can then be quickly and manually compared with the hash calculated on the merchant's side.

hashtab.png

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 under Section 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 Global Gateway e4℠ 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="WSP­EXA­001­01" type="hidden">
  <input name="x_amount" value="1.23" type="hidden">
  <input name="x_fp_sequence" value="123456" type="hidden">
  <input name="x_fp_timestamp" value="1191600622" type="hidden">
  <input name="x_fp_hash" value="4b04d15ccd9007658c2dadc679899ec4" type="hidden">
  <input name="x_show_form" value="PAYMENT_FORM" type="hidden">
  <input name="x_relay_response" value="TRUE" type="hidden">
  <input value="Checkout" 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 Global Gateway e4℠ servers is signed with a cryptographic hash. The name of the hashed field is x_MD5_Hash. It is calculated as the MD5 Hash of the concatenation of the strings:

  • 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 MD5 calculation is performed for the string:

abcdefgh12345WSP-EXAMPL-011234567891.00

Resulting in:

0ae500c0cb7d78f9c26598d6456180dd

The key is configured under the "Security" tab of the Global Gateway e4℠ Payment Pages interface.

responsekey.png

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=&x_test_request=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  
x_test_request TRUE
SurchargeAmount 0
x_tax_exempt  
x_phone  
x_merchant_email  
MerchantProvince BC
Reference_No 1234567
ZipCode  
x_trans_id 2150
x_last_name Testname
x_cvv2_resp_code  
Retrieval_Ref_no 5669951
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:

  1. 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.
  2. The merchant does not have normal access to the payer's cookies, since the Global Gateway e4℠ 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 Code Integration Samples area which demonstrate:

  • How the parameters related to the state of the transaction are evaluated:
    • x_response_code
    • x_response_reason_text
    • exact_ctr
  • How to use parameters sent with the original redirect from the merchant's website to the Global Gateway e4℠ Payment Pages payment form.

 

 

 
Topic is closed for comments