OGW Hosted Payment Integration Guide v2.7.0.0

H OSTED P AYMENT S OLUTION
Orbital Gateway Integration Guide
November 2021
Version 2.7.0.0
Copyright © 2021 JPMorgan Chase & Co. All rights reserved.
All Information contained herein is STRICTLY CONFIDENTIAL AND PROPRIETARY – Not for Use
or Disclosure outside JPMorgan Chase Bank N.A., and its respective affiliates or customers.
This publication is for informational purposes only, and its content does not represent a contract or
agreement, in any form. Chase reserves the right to alter product specifications without notice. No part of
this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical,
including photocopy, recording, or any information storage or retrieval system, without Chase’s
permission.
All brand names and product names used in this document are trade names, service marks, or registered
trademarks of their respective owners. No part of this publication shall be construed as any license,
express or implied, to any of the respective owners’ trade names, service marks or trademarks or any
patents, copyrights or other intellectual property of JPMorgan Chase Bank, N.A., and its respective
affiliates and shall not be used or furnished as any reference and/or in connection with any
advertisement, announcement, release or promotional materials by any persons other than such
respective owners.
Orbital Gateway Hosted Payment Solution What’s New in Version 2.7.0.0
What’s New in Version 2.7.0.0

The following update was made to Version 2.7.0.0:
• Removed duplicate HPF response on a uID Query table
Page 3 of 121
Orbital Gateway Hosted Payment Solution Table of Contents
Table of Contents
What’s New in Version 2.7.0.0 ................................................................................................................................. 3
About This Guide ...................................................................................................................................................... 7
Audience .............................................................................................................................................................. 7
Product Overview ................................................................................................................................................. 7
Hosted Payment Page (HPP) ........................................................................................................................ 8
Hosted Payment Form (HPF) ........................................................................................................................ 9
Supported Browsers ............................................................................................................................................. 9
Implementation Testing ...................................................................................................................................... 10
Getting Started ................................................................................................................................................... 10
Implementation Options ........................................................................................................................................ 11
Hosted Payment Form ....................................................................................................................................... 11
Essential elements for the Integration of HPF ............................................................................................. 11
Technical Prerequisites to HPF Integration ................................................................................................. 11
How Hosted Payment Form Works ............................................................................................................. 12
Parent Page ................................................................................................................................................. 13
PostMessaging ............................................................................................................................................ 14
Callback File ................................................................................................................................................ 15
HPF Parameters .......................................................................................................................................... 16
HPF Customization ...................................................................................................................................... 16
iFrame Implementation ................................................................................................................................ 21
Response Functions .................................................................................................................................... 21
Hosted Payment Page ....................................................................................................................................... 22
Essential Elements for the Integration of HPP ............................................................................................ 22
Technical Prerequisites to HPP Integration ................................................................................................. 22
How Hosted Payment Page Works ............................................................................................................. 22
Payment Page Template ............................................................................................................................. 23
HPP Customization ..................................................................................................................................... 24
Transaction Success Response Page ........................................................................................................ 30
Order Abstraction Service .................................................................................................................................. 31
Order Abstraction Three-Step Process: ...................................................................................................... 31
Order Abstraction Request uID Service ...................................................................................................... 32
Setting Maximum Number of Retries in HPF and HPP ............................................................................... 34
Fraud Mitigation Best Practices ......................................................................................................................... 35
Prevent Website Spoofing ........................................................................................................................... 35
Reduce Bot Attacks ..................................................................................................................................... 35
HPS Addresses .................................................................................................................................................. 36
Page 4 of 121
HPP and HPF Web Addresses.................................................................................................................... 36

Order Abstraction Web Addresses .............................................................................................................. 37
IP Addresses ............................................................................................................................................... 38
Security and Authentication ......................................................................................................................... 38
Functional Processing ........................................................................................................................................... 40
Customer Profile Management .......................................................................................................................... 40
Simplifies Transaction Processing............................................................................................................... 40
Eliminates Risk ............................................................................................................................................ 40
Requesting an Orbital Gateway Customer Profile ....................................................................................... 40
Image CAPTCHA ............................................................................................................................................... 41
Image CAPTCHA for HPF ........................................................................................................................... 41
Image CAPTCHA for HPP ........................................................................................................................... 42
Safetech Tokenization........................................................................................................................................ 42
Safetech Fraud Tools (Stratus Only) ................................................................................................................. 43
Setup Requirements .................................................................................................................................... 44
‘Kaptcha’ Device Data Collection ................................................................................................................ 44
Fraud Analysis Requests ............................................................................................................................. 45
Fraud Analysis Responses .......................................................................................................................... 47
Card Indicators ................................................................................................................................................... 49
Card Indicator Requests and Responses .................................................................................................... 49
Additional Notes........................................................................................................................................... 50
Account Verification ........................................................................................................................................... 50
Supported Card Types ................................................................................................................................ 50
Stored Credential Framework ............................................................................................................................ 51
Stored Credential Introduction ..................................................................................................................... 51
Credential versus Stored Credential ........................................................................................................... 51
Cardholder-Initiated Transactions ............................................................................................................... 52
Profiles Managed by Orbital ........................................................................................................................ 53
CIT Profile Creation ..................................................................................................................................... 53
HPS Parameters ...................................................................................................................................................... 56
Hosted Payment Form ....................................................................................................................................... 56
HPF Request Definitions ............................................................................................................................. 56
HPF Response Definitions .......................................................................................................................... 70
Hosted Payment Page ....................................................................................................................................... 82
HPP Request Definitions ............................................................................................................................. 82
HPP Response Definitions .......................................................................................................................... 96
Page 5 of 121
Frequently Asked Questions ............................................................................................................................... 102

Appendix A: Error Handling ................................................................................................................................ 105
Integration Errors ............................................................................................................................................. 105
Pre-Fail Errors ........................................................................................................................................... 107
Hosted Payment Specific Response Codes .............................................................................................. 107
Orbital Gateway Errors ..................................................................................................................................... 108
Common Orbital Gateway Error Messages ............................................................................................... 109
Appendix B: Payment Form CSS Classes ......................................................................................................... 110
Appendix C: Hosted Payment Admin ................................................................................................................. 113
Hosted Payment Form Admin .......................................................................................................................... 114
HPF URL Configuration ............................................................................................................................. 114
Hosted Payment Page Admin .......................................................................................................................... 115
Appendix D: Parent Page Code Samples ........................................................................................................... 118
uID Request and Response Sample ................................................................................................................ 118
uID init Request (must be a server-to-server request) .............................................................................. 118
uID init Response ...................................................................................................................................... 118
Post Messaging Sample .................................................................................................................................. 118
Callback File Sample ....................................................................................................................................... 120
Page 6 of 121
Orbital Gateway Hosted Payment Solution About This Guide
About This Guide

This guide provides a simplified path to implementing Chase Merchant Services’ Hosted Payment Solution (HPS).
Audience
This guide is intended for use by Merchant Services clients processing payments via online e-commerce, and
Chase personnel assisting with a Hosted Payment Solution implementation. To take advantage of this interface, a
developer should be familiar with web-based forms and sending and receiving name-value pairs of data.
Note: Due to account setup restrictions, this product is only intended for U.S. Merchant Services clients.
Product Overview
The Hosted Payment Solution allows clients to offer a secure interface for customers to submit payment
information without the overhead of maintaining sensitive data in transit. Payment processing within this secure
environment removes the client from potential Payment Card Industry (PCI) liability.
HPS can perform authorization requests and create Orbital profiles (stored credentials) to be used for subsequent
transactions, but it cannot process transactions that use profiles, update profiles or delete profiles. Transactions
that use Orbital profiles require an Orbital API or the Orbital Virtual Terminal to process. HPS does not perform
voids, refunds, mark for captures or subsequent authorization transactions.
Page 7 of 121
High Level Process Flow: Illustrates how the flow of information works in a Hosted Payment environment.
1. A Request Unique ID (uID) is sent to the Request Payment interface.
2. The Request Payment interface sends the uID to the Hosted Payment interface.
3. The Hosted Payment interface inputs the customer information.
4. The customer information is used to process the payment.
5. After the payment is processed, the customer experience is completed.
The Orbital Gateway’s secure servers receive the checkout order and payment request. One of two Hosted
Payment Solutions is available to the client: Hosted Payment Page and Hosted Payment Form.
Hosted Payment Page (HPP)
1. The HPP provides a secure hosted payment interface to the customer that mirrors the client’s website.
2. Users are redirected from the merchant website to the HPP where they submit their card information.
3. Upon a successful transaction, the user is redirected back to the merchant website on the return URL along
with the response URL.
Page 8 of 121
Hosted Payment Form (HPF)
1. The HPF provides a payment form in an iFrame (Inline Frame) that allows users to submit their card
information via the client’s website (hosted by Orbital Gateway)
2. The cardholder data and payment transaction is securely processed by the Orbital Gateway. Payment
information can be stored in a customer profile, triggering a reference value that is not directly engineered
from payment information. The customer profile safely abstracts a client from sensitive customer data and can
be used, retrieved, or updated at any time.
Chase Merchant Services maintains two proprietary Authorization and Deposit platforms. The Orbital Gateway
processes to both platforms using identical transaction information as presented in this specification, except for
any features that may only be available on one of the two platforms. Contact the merchant Analyst or Relationship
Manager if the merchant is unsure of the correct platform where the client account resides.
Supported Browsers
Orbital’s Hosted Payment Solution (HPS) should be used with browser versions that are supported by their
developers and can run on current versions of Operating System (OS). After a company ends the support cycle
for an OS version, any browsers intended for that OS version are not supported.
When a browser reaches end-of-life support by its developer, HPS will no longer support it, but will not
intentionally disable it. Updates and patches made to HPS for security or to enhance the product may result in
system breaks if deprecated browsers are used.
Supported Browser List
Browser Versions
Google Chrome 64.0.3282 and higher
Firefox 68.1.0 and higher
Firefox iOS 19.1
Firefox Android 68.1.1
Safari 11.1.2 and higher
Microsoft Edge 40.15063 and higher
Internet Explorer 11 (final version of IE and nearing end of life)
Page 9 of 121
Implementation Testing
Before aggregators, software vendors or merchants can process using this interface, the implementation must go
through the appropriate testing process with Chase Merchant Services. Work with your Merchant Services
Representative to schedule testing as necessary. Every feature that you will implement must go through
implementation testing.
Getting Started
The following links are to help guide the merchant to the steps required to complete the merchant Hosted
Payment Solution implementation:
1. Fill out the HPS Admin Area.
2. Build Parent Page.
3. Link to the PostMessaging Script or download the Callback File.
4. Build the uID Request.
5. Send Request to Order Abstraction URL and Get uID back.
6. Use uID to load Hosted Payment Form (HPF) or Hosted Payment Page (HPP).
7. Create Customer-Facing Response Handling (Javascript functions).
8. Create Merchant-Facing Response Handling (uID query).
Page 10 of 121
Orbital Gateway Hosted Payment Solution Implementation Options
Implementation Options
The Orbital Gateway Hosted Payment Solution (HPS) makes two separate but similar interfaces available: the
Hosted Payment Page and the Hosted Payment Form.
Note: Custom modifications made to HPS that are outside of the scope of this guide will not be supported.
Hosted Payment Form

The Orbital Gateway Hosted Payment Solution also provides a Hosted Payment Form (HPF) that allows the
merchant to serve a payment collection form within the framework of the merchant existing web page. The
payment form displays in an inline frame (iFrame) set within a website. The contents of the iFrame are hosted by
the Orbital Gateway, completely separate from other content on the page.
Essential elements for the Integration of HPF
• An iFrame to display the payment form
• A suite of response functions on the merchant webpage to handle transaction and error data
• PostMessaging or a callback.html file to direct responses from Orbital Gateway to the correct response function
• A Cascading Style Sheet (CSS) file to set the appearance of the payment form
Optional element for the integration of HPF: A transaction response API call
Note: To request a payment form, set the iFrame source (src) attribute to the HPF request URL.
Technical Prerequisites to HPF Integration
• Website must be accessible via the internet
• Website must use HTML to generate distinct web pages
• Website must have a digital certificate installed (private or shared) with TLSv1.2 protocol enabled in order to post
to the service and to have the merchant images and CSS incorporated into HPF.
Note: Posting to the HPF service from a non-TLS URL results in a 404 error. Only secure connections are
accepted by the HPF servers. Merchant Services does not support local SSL storing/caching, as they are
frequently updated
Page 11 of 121
How Hosted Payment Form Works
Hosted Payment Form Flow Diagram
Page 12 of 121
1. A customer creates an order on the merchant website. When the customer indicates they are ready to check
out, they are directed to a page within the merchant website framework that includes a particular iFrame.
2. The content of this iFrame is derived by a call out to the Orbital Gateway Hosted Payment servers. The
customer then inputs the proper payment information into the iFrame and submits the payment.
3. When the customer submits the payment information, the Orbital Gateway validates the formatting of the
request.
4. If the information is properly formatted, processing continues. If the processing is unsuccessful:
a. An error is displayed on the page.
b. The customer must correct the information or reach out to the merchant for assistance.
After a payment is successfully processed, the payment information can be stored in a customer profile, if
desired. The customer profile ID (also known as a customer reference number) is a unique reference value
that is not derived from the customer’s information in any manner.
5. When the transaction is completed:
a. The merchant payment site displays the status of the request to the customer.
b. Orbital Gateway returns the payment information in an XML format to the merchant.
Parent Page
A parent page must be present on the merchant company website and must include an iFrame to display the
Hosted Payment Form. The merchant parent page must also include the Response Functions to handle the data
returned by the HPF during transaction processing.
Note: Modern web browsers do not allow the parent page to access data within the child iFrame. However, the
best practice is to ensure that the merchant parent page is not editable or subject to malicious action from users.
See parent page code samples in Appendix D.
There are two methods of response handling:
• PostMessaging (preferred)
• Callback File
Page 13 of 121
PostMessaging
PostMessaging redirects responses and error messages to the iFrame parent page. PostMessaging eliminates
cross-domain restrictions and safely allows cross-origin communication between a page and an iFrame
embedded within.
To use postMessaging, the merchants need to add the hpfParent.min.js script on their parent page as
shown below:
Sandbox environment:
<script src="https://www.chasepaymentechhostedpay-
var.com/hpf/js/hpfParent.min.js"></script>
Production environment:
<script
src="https://www.chasepaymentechhostedpay.com/hpf/js/hpfParent.min.js"></script>
When HPF loads, it attempts to send an init postmessage to the parent page, and if it receives a response it
knows the merchant has implemented postMessaging and sets a flag indicating that it is the method of
communication to be used going forward.
PostMessage Request and Response
If no response is received, it defaults to the callback.html method. Although callback.html is not required when
using postMessaging, it can be used for compatibility with older browsers and some legacy corporate
implementations.
Note: Merchants must not load the postMessaging script with the async or defer attributes.
PostMessage Requirements
The hpfParent.min.js script must be loaded before the iframe loads so that it is reached on the first init
message. If for some reason the iframe sends the init message before the parent script is ready, it would cause
it to default to the callback.html method.
Page 14 of 121
If callback.html is not implemented by the merchant, they would not receive any response from HPF. So the
merchant must make sure that the hpfParent.min.js script is loaded before the iFrame. The callback.html
method may be used as an alternative to postMessaging for improved backward compatibility.
PostMessage Response Handling
There are two optional callback functions: hpfReady() and scrollRelay(). The hpfReady() function
notifies the parent page that the form has finished loading and scrollRelay relays the x, y coordinates of each
scroll event in the iFrame.
The alias function names for postMessaging are handlePaymentErrors(), completePayment(),

startPayment(), cancelPayment().Rather than a pipe delimited string of error codes,
handlePaymentErrors() returns a single object containing a list of error codes, the gateway code, and
message.
PostMessages that are sent or received can be viewed in the DevTools of a browser. See Appendix D for
samples in response handling.
The hpfReady() function will trigger after the form finishes loading.
Callback File
The callback file redirects responses and error messages to the iFrame parent page. The content of the callback
file is provided on Developer Center under Orbital APIs / Hosted Payment Processing API download page. If the
callback is viewed in a browser, white page displays black text with the version number, for example, Version
1.6.4.1.
When the Gateway responds to an action taken on the merchant HPF, it looks for the callback page in the
location specified within the Hosted Payment Page Admin screen or with the callback_url parameter in the
payment form request. When the HPF system responds to an action taken on the merchant's HPF form, it looks
for the callback page in the location specified within the Hosted Payment Page Admin screen or with the
callback_url parameter in the payment form request. The callback page then directs the response to the
appropriate response function on the merchant iFrame parent page. For more information about response
handling, see Customer-Facing Response Handling.
Callback Page – File Requirements
• The callback file is required if postmessaging is not being used, and the callback file must not be altered.
Page 15 of 121
 Integrations with modified callback files are not supported.
 Customization of the callback page is not supported.
• The callback page must match exactly the merchant designated callback URL or what is passed in a transaction
request.
• The callback page must be accessible via the Internet to the Orbital Gateway servers without a login prompt.
• The callback page must be hosted on the same domain or subdomain as the form page that contains the
response functions.
HPF Parameters
The Orbital Gateway requires static parameters be configured before the Hosted Payment Form can be built
within the merchant website. The values for these parameters must be configured in the Hosted Payment Page
Admin screen of the merchant Virtual Terminal. Refer to the HPF URL Configuration for additional information.
• Callback URL=URL of the callback page
• Return URL=URL of the page which handles Response XML returned by the HPF
Note: An invalid URL can cause delays in processing. Ensure that even if you are not using the Return XML
response, the return URL is valid/resolvable.
• CSS URL=URL of style sheet for the HPF
The source URL of the iFrame may override the callback URL and CSS URL set in the Gateway.
HPF Customization
The Hosted Payment Form exists as an iFrame element within a merchant’s parent page. The size and
placement of the HPF itself within the page is designated entirely within that parent page.
The payment fields presented in a Hosted Payment Form are defined by the request parameters, which are
based on a combination of the method of payment requested, the formType request element, and the
collectAddress request element.
Page 16 of 121
Payment Field Customization
The formType request element allows for several different variations of field placement: Short, Tall, iPhone,
Mobile Friendly, Div Based or ECP tableless. See formType in HPF Request Definitions for more information.
Sample HPF – formType 0 – Short
Sample HPF – formType 1 – Tall
Page 17 of 121
Sample HPF – formType 4 –Mobile phone friendly
Sample HPF – formType 7 – DIV based
Sample HPF – formType 9 – ECP Tableless
Additional parameters can be used to add duplicate fields on the form for Routing Number and Account Number
to verify the entered data:
• confirm_routing_number=1
• confirm_account_number=1
Page 18 of 121
Sample HPF – Confirm Routing and Account Numbers
Note: If using HPF in conjunction with the Early Warning Service (EWS), ensure that the account holder name is
included in the form. Leaving the account holder’s name blank will result in a failure at settlement. The account
holder name can be made mandatory by adding required=all in the post message.
Collection of the billing address is an optional function of the Hosted Payment Form. Address Verification Service
(AVS) data may be submitted by the merchant as part of the HPF request parameters, or it may be submitted on
the same form as the payment information input by the consumer.
The collectAddress element may be set to request the customer provide a billing address. Either a domestic
or an international address is supported, based on the collectAddress value. See collectAddress in HPF
Request Definitions for additional information.
Sample HPF – collectAddress 0 – No Address:
Page 19 of 121
Sample HPF – collectAddress 1 – Domestic Address:
Sample HPF – collectAddress 2 – International Address:
Page 20 of 121
Sample HPF – collectAddress 3 – Zip Code Only
Cascading Style Sheets (CSS)
Additional customization is available by modifying the CSS elements used by the Hosted Payment Service when
producing an HPF. The Hosted Payment Form does not use a merchant-defined template page, so the style
sheet which contains these CSS elements must be an external style sheet. A style sheet is used to match the
formatting of the HPF to the merchant website calling the form. The style sheet can also disable and change the
appearance of the submit button after it has been clicked. The URL of the style sheet is defined within the Hosted
Payment admin page or using the css_url parameter in the payment form request.
Several different base styles are available for the hosted pay form. These options are set by sending a value for
formType in the form request post. Refer to the formType field in the HPF Customization section and Appendix
B: Payment Form CSS Classes for more details.
iFrame Implementation
Customers can interact with the payment interface that is contained within an iFrame on the merchant payment
website. The contents of the iFrame are determined by setting the “src” attribute to the URL of the desired
content. To request a payment form, the “src” attribute of the iFrame is set to the intended endpoint.
Response Functions
The response functions handle the data returned to the customer by the HPF during transaction processing. The
response functions are JavaScript functions that must be located in the root frame (window top) of the merchant
parent page. Refer to Customer-Facing Response Handling.
Page 21 of 121
Hosted Payment Page

The Hosted Payment Page (HPP) service is utilized to supply a full checkout page to a customer on behalf of a
merchant or client.
Essential Elements for the Integration of HPP
• A payment request form
• A template payment page
• A transaction success response page
Technical Prerequisites to HPP Integration
• Website must either be publicly accessible via the internet, or allow HPS requests through a firewall.
• Website must use HTML to generate distinct web pages.
• Website must have a digital certificate installed with the TLSv1.2 protocol enabled in order to utilize the Hosted
Payment service. Connection requests coming from servers using protocols older than v1.2 will fail.
 TLS certificate must also be installed on the parent page in order to incorporate images and use
 Private or shared certificates are allowed
 Self-signed or root certificates are not supported
Note: Merchant Services does not support local SSL storing/caching, as they are frequently updated.
How Hosted Payment Page Works
A customer navigates a website to create a purchase order. The customer completes the order in the shopping
cart, and then selects a “checkout” option. This checkout process includes a call to the Orbital Gateway Hosted
Payment Service to collect the customer’s payment data.
The Orbital Gateway receives the checkout request, starting the hosted payment process. A standardized
template page is retrieved from the website design in real time. Any potentially malicious code is purged, and the
template is merged with a securely generated payment collection form.
Page 22 of 121
The Orbital Gateway HPP interface presents this secure hosted payment page to the customer, which emulates
the merchant website. The customer retains access to all links and live navigation of the merchant website via the
template page.
The Hosted Payment Page itself is served from an Orbital Gateway server. All payment information is handled
between the customer and the Gateway. After a payment has processed, the payment information can be stored
in a customer profile, if desired. The customer profile ID (also known as a customer reference number) is a unique
reference value that is not derived from the customer’s information in any manner.
After the payment transaction is complete, the customer is connected directly back to the Transaction Success
Response page on the merchant website. The response page interprets the order status at the merchant
discretion and includes transaction information such as masked payment data. If a customer profile is requested,
that profile reference value can be used for subsequent authorizations.
See the section HPP Request Definitions for more information.
Payment Page Template
The payment template is a page on the merchant website used to present the Hosted Payment Page. The
template includes user session logic of the payment page, along with a [[FORM INSERT]] value in the content
area. The service reads the contents of the page, searches for [[FORM INSERT]], and replaces it with the
customer payment form.
The URL of the template on the merchant website is passed to the Orbital Gateway in the
content_template_url post variable.
Rules that Apply to the Payment Template Page
• [[FORM INSERT]] value must be placed wherever the payment form is to appear
• Page title and any text above and/or below the [[FORM INSERT]] must be specified within the template
• URL of the payment template page can be any URL of the site, and must be accessible over HTTPS protocol
and directly available to a web browser
• Use absolute URLs for Cascading Style Sheet (CSS) and image SRC values.
• CSS file and images must be accessible via the HTTPS domain
• Template page must allow for the user session to be set via the URL
• Page should render using the application template logic and preferences set for the merchant website
Page 23 of 121
• HTML output (<script> and <iframe> tags) is removed for security (ensure the payment template page
renders correctly without these tags)
HPP Customization
The central element to the look and feel of a Hosted Pay Page is the merchant’s template page. The Orbital
Gateway does not place any limitations on the look and feel of the template page, outside of the basic security
procedures outlined in Payment Page Template.
Processing Overlay
The Processing Overlay feature is available on the Hosted Pay Page and creates an “in progress” screen to
overlay the Payment Page after the “Submit” button has been clicked by the customer, ensuring that the customer
sees that the transaction is still in progress and should not leave the page or click on the “Back” button. This
prevents any processing errors that may occur should the customer attempt to leave the Payment Page due to
perceived lack of activity. To enable the Processing Overlay feature, set the processing_overlay request
parameter to “1” for the merchant HPP request: processing_overlay=1.
Sample HPP – Processing Overlay:
Page 24 of 121
Payment Field Customization
The payment fields presented on a Hosted Payment Page are defined by the request parameters.
Form Type
The form request element allows for several different variations of field placement: OS Commerce style, Magento
style, Mobile first, tableless or ECP tableless. See form in HPP Request Definitions for more information.
Sample HPP – form osc – OS Commerce style:
Sample HPP – form mage – Magento style:
Page 25 of 121
Sample HPP – form mobile_first –Responsive Form:
Sample HPP – form tableless – single column tableless form:
Sample HPP – form ecp_tableless – single column tableless for ECP:
Page 26 of 121
Additional parameters can be used to add duplicate fields on the page for Routing Number and Account Number
to verify the entered data:
• confirm_routing_number=1
• confirm_account_number=1
Sample HPP – Confirm Routing and Account Numbers
Note: If using HPP in conjunction with the Early Warning Service (EWS), ensure that the account holder name is
included on the page. Leaving the account holder’s name blank will result in a failure at settlement. The account
holder name can be made mandatory by adding required=all in the post message.
Address Fields
The collectAddress element may be set to request the customer provide a billing address. Either a domestic
or an international address is supported, based on the collectAddress value. See collectAddress in HPP
Request Definitions for additional information.
Sample HPP – collectAddress 0 – No Address:
Page 27 of 121
Sample HPP – collectAddress 1 – Domestic Address:
Sample HPP – collectAddress 2 – International Address:
Sample HPP – collectAddress 3 – Zip Code Only
Page 28 of 121
Language
Text presented within the template page by the Hosted Payment Service defaults to English as the language of
choice. Additional options for French Canadian or North American Spanish translations are available by modifying
the lang element when submitting a request to the Hosted Payment Service.
Displaying the Transaction Amount
In order to ensure the transaction amount is displayed on the Hosted Payment Page pass the
collect_total_amount parameter along with an appropriate value:
0 = Do not collect total amount on payment page
1 = Display total amount as read only field
2 = Collect total amount with editable field
Sample code:
<input type=“hidden” name=“collect_total_amount” value=“1” />
Standard CSS may be used to further stylize the input fields. Most elements use a class named “main,” which
may be modified within the template page as necessary to stylize the payment fields presented to the customer. A
style sheet is used to match the formatting of the HPP to the merchant website calling the form. The style sheet
can also disable and change the appearance of the submit button after it has been clicked.
Several different base styles are available for the hosted payment page. Refer to the HPP Customization section
for more details.
Classes, IDs and tags used to stylize the payment page:
• H2 (form title)
• table
• tr
• td.main
• span.main
• input
Page 29 of 121
• select
• #submit
• class=“disabled” – Hides the submit button after it has been pressed
• #error_message – DIV containing the error message
• span.error_message – Surrounds the error message text
Note: The payment page displays an error at any time a request fails validation. To customize the error message
text, set a hidden DIV in the merchant Payment Page Template HTML.
Example: <div id="errorMessageSuffix" style="display:none;">Please try again.</div>
Sample HPP–Examples of CSS Customization (Before & After)
Transaction Success Response Page
After the payment transaction is complete, the customer is connected directly back to the Transaction Success
Response page on the merchant website. The response is returned as name/value pairs in an HTTP $_GET
(postback) to the supplied return URL.
HPP returns the customer to the merchant website when:
• A payment is successfully processed.
 customer is directed to the return_url
• The customer leaves the page by clicking the “Cancel” button.
 customer is directed to the cancel_url, or
 customer is directed to the return_url if the cancel URL is not specified
Page 30 of 121
• A payment receives a decline or error, and the number of allowed attempts is exceeded.
 Declines and errors are treated as user input error. The customer is shown the error message (with suffix
if present) and asked to try again.
 Limit these errors by setting a max_user_retries value in the request.
Note: If the customer leaves the page by clicking any link in the template HTML, the customer is no longer on the
HPP.
Order Abstraction Service

Standard processing of the Hosted Payment Service utilizes the customer’s browser to initiate the generation of a
Hosted Payment Page or Form. Orbital Gateway requires the merchant to utilize the security feature built into
HPS known as Order Abstraction to generate a secure payment interface for the merchant customers.
Order Abstraction allows the merchant to hide transaction details and the HPP/HPF request elements from the
customer’s browser. All parameters and values must be sent in a server-to-server request to generate a unique
uID, which can then be used to initiate either HPP or HPF.
The merchant’s system makes a GET call to generate the uID with 90 seconds to create an HPP/HPF payment
form using the uID. This means that the merchant has 90 seconds to pull up HPP or HPF before the uID expires
(this does not apply to the time taken to fill out the form). Exceeding the 90-second timeframe requires the
merchant to create a new uID. After the transaction is complete, the transaction response must be obtained using
a server-to-server query.
Order Abstraction Three-Step Process:
1. uID init request (Required): Send the HPF request parameters or HPP request parameters in a server-to-
server request to the Direct Services init address to generate a uID.
2. uID redeem (Required): Pass the uID to the HPP/HPF endpoint to request the payment page/form (see HPP
and HPF Web Addresses).
Note: uID is case sensitive
3. uID transaction query (Optional): Send the uID and the Account ID/API Token to the query address to
retrieve response details.
Page 31 of 121
Order Abstraction Request uID Service
To use Order Abstraction, the merchant server must submit the request elements and the Secure API Token as
an HTTPS GET message to the specified Order Abstraction hosted payment service address. Order Abstraction
begins before payment data is input into the payment interface provided by the Hosted Payment Service. Forced
Order Abstraction is configured in the Hosted Payment Page Admin screen and will require that all requests utilize
Order Abstraction. Refer to Appendix C: Hosted Payment Admin.
Order Abstraction Flow
Page 32 of 121
HPP uID init Request
https://www.chasepaymentechhostedpay-
var.com/direct/services/request/init/?hostedSecureID=cpt123456789012ab&hostedSecure
APIToken=12345a12b123c1d1e12345f1g12hi1jk&action=buildForm&content_template_url=htt
ps://company.mytestsite.php&return_url=https://companytest.com&cancel_url=https://c
ompanytest.com&total_amt=1.00&order_id=hps123456
uID init Response
uID=337DA68A0915EAEBF4F6360148218A88
Note: The uID is a one-time use token with respect to generating a payment interface to the cardholder. A
merchant has 90 seconds to redirect the consumer to the HPP or HPF, or the uID token will expire. Order
Abstraction must be re-initiated if the end user decides to refresh the page.
The merchant browser then invokes the Hosted Payment Service, passing only the uID element via HTTPS
POST. No other request elements are sent. The Hosted Payment Interface retrieves the request parameters
associated to that uID and produces a payment interface for the customer.
uID Request
uID=32F2B889D3812A3B5DFC00471279DA05
After the transaction is complete, response data is returned to the customer browser and (optionally) the
merchant. The response echoes the uID, returns the transaction status, and suppresses all other response
elements. Also refer to the table, HPF JSON Response on the Callback File. Response handling proceeds as
normal.
HPP Response
code=000&message=Success&uID=32F2B889D3812A3B5DFC00471279DA05
HPF Response
code=000&rurl=https://www.chasepaymentechhostedpay-
var.com/hpf/1_1/&message=Success&uID=32F2B889D3812A3B5DFC00471279DA05&profileId=cpt
123456789SB
Page 33 of 121
The merchant server may retrieve the suppressed elements by submitting a query request as an HTTPS GET to
the specified hosted payment service address. The transaction results associated with the uID token are queried,
and response data is returned to the merchant server for response handling. The Merchant Services Secure ID
(hostedSecureID) in the uID query request is case sensitive and must be expressed as “cpt” or the query will be
unsuccessful.
Note: In the HPF response, &profileId allows additional logging in the HPF system against the callback file
used by the merchant.
Setting Maximum Number of Retries in HPF and HPP
In Order Abstraction integration, passing max_user_retries count will restrict the number of retry attempts with
incorrect payment information; thereby curbing fraudulent retries.
Pass the parameter max_user_retries and its value in the merchant uID initialization request.
In HPP, the user is redirected to return_url after max retry count is reached.
In HPF, “Complete” button changes to “Finished” after max retry count is reached.
A retry attempt will only work if an error is returned by the gateway. It will not work on pre-fail errors which are
returned by the built-in form validation in HPP/HPF.
Sample request with example:
var.com/direct/services/request/init/?hostedSecureID=cpt123456789012ab&hostedSecure
APIToken=12345a12b123c1d1e12345f1g12hi1jk&action=buildForm&css_url=https://companyt
est.com/cptcodebuilder/hpfstyle.css&callback_url=https://companytest.space/cptcodeb
uilder/callback.html&sessionId=7u0sliplohkhdpt6f5625hm6k1&max_user_retries=
5&amount=1.00&orderId=hps123456
If max_user_retries is set to “5,” then a customer will be redirected to the defined return_url on the 6th
failed authorization attempt on the hosted pages.
Page 34 of 121
Fraud Mitigation Best Practices
Prevent Website Spoofing
Website spoofing, although very rare with HPS, is the act of creating a replica of a trusted site with the intention of
misleading shoppers to a phishing site. Normally, the spoof website will adopt the design of the target website,
and it sometimes has a similar URL.
Merchants are required to integrate HPS using Forced Order Abstraction. Order Abstraction hides key data that
could be captured and used by a bot performing systemic monitoring.
Implementing IP allow lists will only allow calls from designated IP addresses as it travels from a merchant’s
server to HPS servers when initiating a transaction.
Reduce Bot Attacks
A bot (short for “robot”) is an automated program that runs over the Internet that is used to exploit or disrupt a
merchant’s site. Some bots run automatically, while others execute commands after they receive specific input.
Attackers often create an account on a merchant’s site or use the guest checkout process and use a bot to run
transaction attempts. Requiring a guest to only supply an email address is not enough to stop these attacks.
• Ensure guests can take steps to create an account.
• Require a two-step validation.
Attackers can also attempt to test cards for legitimacy to determine whether stolen or computer-generated card
numbers are valid. Bot traffic may not be detected by a merchant if the merchant is not capturing all responses.
This is often the case if a merchant’s developers assume cardholders will occasionally need to retry their
transaction to correct an invalid card entry. Typically, retries of a single transaction are seen, and at times tens of
thousands.
• Implement max_user_retries into all transactions to limit the number of retries on a transaction.
• Using a low max_user_retries value to reduce the likelihood of an attack. For example,
max_user_retries=1 will allow two attempts (initial attempt and a retry attempt), preventing repeated retries
on a single transaction.
Page 35 of 121
Some merchants reuse the same order ID on all transactions, while others do not use an order ID at all. Reusing
the same order ID for all transactions can limit protections available with HPS and increase the potential for bot
traffic.
• Encourage cardholders to create an account.
• Validate guest accounts / email addresses.
• Require Address Verification Service (AVS) and Card Security Value (CVV) validation.
• Adopt CAPTCHA to most effectively thwart bot attacks, as it requires human input into a data field.
Note: A merchant must not use formtype 5 in HPF integrations. Form type 5 was originally designed for flip
phones, and CAPTCHA and other key security features are not available with form type 5. It was deprecated
years ago and is out of scope for any security updates. All existing merchants must select another form type. See
the valid values for formType in HPF Request Definitions.
HPS Addresses
HPP and HPF Web Addresses
The merchant must complete implementation testing via the testing system and have the integration approved
before submitting transactions to the production system.
HPS Testing System
Hosted Payment Page (HPP):

https://www.chasepaymentechhostedpay-var.com/securepayments/a1/cc_collection.php
Hosted Payment Form (HPF): https://www.chasepaymentechhostedpay-var.com/hpf/1_1
HPS Production System
Hosted Payment Page (HPP):

https://www.chasepaymentechhostedpay.com/securepayments/a1/cc_collection.php
Hosted Payment Form (HPF): https://www.chasepaymentechhostedpay.com/hpf/1_1
Page 36 of 121
Order Abstraction Web Addresses
When submitting a request, use the HTTPS GET method to submit the expected request elements, including the
hostedSecureAPIToken name-value pair, to the following addresses:
Production
https://www.chasepaymentechhostedpay.com/direct/services/request/init
Testing
https://www.chasepaymentechhostedpay-var.com/direct/services/request/init
To process a request, direct the merchant browser to the appropriate Address.
The uID token associated to a request must be used to retrieve the corresponding response elements. To
retrieve this information, use the HTTPS GET method to submit the uID of the request, as well as the
hostedSecureID and hostedSecureAPIToken of the associated merchant to the following addresses:
Production
https://www.chasepaymentechhostedpay.com/direct/services/request/query
Testing
https://www.chasepaymentechhostedpay-var.com/direct/services/request/query
Page 37 of 121
IP Addresses
The following IP addresses need to be added to the merchant firewall allow list to ensure that the transaction
process flows without interruption:
Production Environment Inbound and Outbound
40.143.178.128/25
173.237.133.128/25
Testing Environment Outbound
3.218.44.149
34.197.32.87
54.196.87.235
54.85.151.115
Testing Environment Inbound Domain Name
chasepaymentechhostedpay-var.com
Security and Authentication
Given the inherent risks associated with processing transactions over the Internet, the Orbital Gateway has the
following two requirements:
1. Encrypted traffic to prevent interception of the payload
The Orbital Gateway Hosted Payment interface must be accessed using the https protocol so that private
information is encrypted and transferred securely. This requires the use of a Transport Layer Security (TLS)
implementation. Refer to Hosted Payment Page and Hosted Payment Form for additional information on the
digital implementation testing requirements.
Page 38 of 121
2. Authentication of the source request generation
When a shopping cart makes a call to invoke the Hosted Payment Solution, the Orbital Gateway requires a
Secure Account ID to validate the request. The Orbital Gateway then compares the source of the request against
a list of authorized websites and moves forward with the request.
In addition, some requests are made in a server-to-server manner. All such requests require a Secure API Token,
in addition to the Secure Account ID.
Both of these data elements are assigned to a merchant by the Orbital Gateway at the time the Hosted Payment
Solution is enabled.
Page 39 of 121
Orbital Gateway Hosted Payment Solution Functional Processing
Functional Processing
Customer Profile Management
The Orbital Gateway includes functionality called Customer Profile Management, which allows cardholder data to
be stored with the Orbital Gateway. Profile Management is available while using a Hosted Pay Page or Hosted
Pay Form, but is not required on a transactional basis.
Simplifies Transaction Processing
After a profile is created, subsequent transactions can be processed through any online interface or the Orbital
Virtual Terminal (VT) simply by referencing the customer Profile and filling in any additional information not stored
in the profile.
Eliminates Risk
Using the Customer Profile Management feature eliminates the need to store sensitive information about a
customer on the merchant database, allowing the merchant to focus on business. It also allows Chase Merchant
Services to focus on securely processing the merchant transactions.
Requesting an Orbital Gateway Customer Profile
The merchant can request a customer profile via the HPP or the HPF during a regular payment transaction, or by
making a new token-only request without performing a transaction.
To request a token, include the hosted_tokenize element in the merchant request. This element has two
possible values:
• store_only – Creates a customer profile without submitting the transaction for approval
• store_authorize – Creates a customer profile “on-the-fly” while submitting the transaction for approval
To request a specific, unique token value for a customer profile, include the customerRefNum element in the
merchant request. The profile ID is generated automatically when the customerRefNum is not present.
Any errors with profile creation will be returned as a profileProcStatus error. These errors should not prevent a
transaction from processing.
Page 40 of 121
Note: For field parameter information, see the Hosted Payment Page and the Hosted Payment Form.
Image CAPTCHA
The term CAPTCHA is a program that is used to protect websites against bot attacks. An image-based
CAPTCHA option is available for HPF and HPP to provide increased security and reduce the likelihood of
fraudulent activity. This option will prevent browser based automated fraud by requiring a user to manually select
the correct answer for the CAPTCHA.
To use this feature, call Merchant Services support to enable it on the Chase Secure ID.
Image CAPTCHA for HPF
After Image CAPTCHA is enabled for HPF, the cardholder will see a pop-up where they must enter the text from
the image to submit the transaction. An audio CAPTCHA button is available to allow visually impaired users to
hear the pronunciation of the CAPTCHA code, and then type the spoken code from the image to submit the
transaction. If an incorrect answer is submitted, a pre-fail error 380 will be returned.
HPF CAPTCHA
Page 41 of 121
Image CAPTCHA for HPP
After Image CAPTCHA is enabled for HPP, the cardholder will see a captcha on the payment page. After they
select the correct answer, the CAPTCHA will be replaced with the payment form. If an incorrect answer is
submitted, an error will be shown on the page. An audio CAPTCHA button is available to allow visually impaired
users to hear the pronunciation of the CAPTCHA code, and then type the spoken code from the image to submit
the transaction. After four unsuccessful attempts, the user will be redirected to the return URL with the following
CAPTCHA related responses, along with other response parameters:
code=380&message=CaptchaRetryExceeded&action=captcha
Default CAPTCHA and CSS Styled
Safetech Tokenization
Merchant Services Safetech tokens can be used to replace a customer’s payment data with a value (or token).
This capability allows merchants to avoid storing and transmitting data that could be targeted by hackers by
protecting payment account information in transit and at rest. As a result, this reduces the risk of card data
exposure in case of a breach and also reduces chargebacks. Merchants can also use the same token across
multiple Merchant Services engines.
Page 42 of 121
Safetech Tokens must be enabled for the merchant in order to use them. If using Safetech Tokens alongside
Profile Management, profiles must be enabled on the Merchant or Chain account level. See the Virtual Terminal
User Guide located in Developer Center.
To use Safetech tokenization, a merchant must send the following parameters in the transaction requests:
requestSafetechToken=1
mitMsgType=CSTO, CREC, CINS, CGEN or CEST
Visa, ChaseNet, Mastercard, American Express and Discover support the use of Safetech Tokens.
When a transaction is processed, a Safetech token will be returned with the safetechToken parameter along with
other response parameters. A sample transaction response is as follows:
transId=5EF61D0F7EAD54C8E1163EDAB30EAEF5121154B1&appCode=tst248&name=John+Doe&payme
ntType=CC&ccNumber=XXXXXXXXXXXX4448&expMonth=01&expYear=2027&ccType=Visa&cardBrandS
elected=Visa&CVVMatch=M&AVSMatch=3&safetechToken=4444440223074448
Safetech Fraud Tools (Stratus Only)

The Orbital Gateway supports the Safetech™ Fraud Tools service. This advanced fraud scoring technology is
offered to Stratus (BIN 000001) merchants, enabling the detection of fraud patterns that are more difficult to
identify through traditional fraud management tools.
Merchants create a custom fraud analysis strategy for their business using the Safetech Agent Web Console. The
Safetech service applies this strategy to provide the following benefits:
• Minimize lost sales and the associated costs of combating fraud
• Control levels of fraud exposure with customizable tools
• Maximize order conversion, increasing your revenue
The Safetech service is fully integrated with Orbital Gateway processing. The overall process flow is described as
the following:
1. A consumer navigates to the checkout page.
2. The merchant sends an HPP or HPF request, including any additional or optional elements available, to the
Hosted Payment Service.
3. The Hosted Payment Service produces a payment interface for the customer to enter payment data. The
‘Kaptcha’ Device Data Collection seamlessly captures location and device data from the consumer.
Page 43 of 121
4. The consumer subsequently submits the transaction information for approval.
5. In the payment response, the Safetech fraud score information is included with the authorization.
a. A dynamic suite of detectors are utilized to perform real-time checks on over 200 variables, to produce a
riskScore from 1 to 99
b. A higher riskScore indicates a higher risk.
6. Based on the Safetech response, the merchant determines whether to complete or reject the approved
transaction.
 An alternative Orbital Gateway interface must be used to Void or Reverse the transaction.
Important:
Merchants may consider the request or response information provided by the Safetech Fraud Tools to be
sensitive information. Orbital Gateway requires merchants use Order Abstraction functionality to maintain
cardholder information security. See Order Abstraction.
Setup Requirements
For more information on the program, including how to obtain a Safetech Merchant ID (used in addition to the
hostedSecureID) and the assignment of a risk analyst, contact your Account Executive.
The risk analyst:
• Provides ongoing monitoring of rule strategy effectiveness, including modification of rules as needed
• Assists with creation of fraud strategy and establishment of respective custom fraud rules
Configuration within the Virtual Terminal’s Hosted Pay Page Admin screen is necessary for any merchant who
wishes to utilize Safetech Fraud Tools. See Appendix B for more information.
‘Kaptcha’ Device Data Collection
The Device Data Collector (also referred to as “Kaptcha”) collects and analyzes data from the customer’s browser
as a function of the Safetech Fraud Tools. The information collected by the Kaptcha process can then be applied
to a transaction to produce a more accurate fraud score. Use Kaptcha when the end user of the payment page is
the cardholder.
Note: In this document, the term “Kaptcha” is not related in any way to the common authentication practice of
CAPTCHA.
Page 44 of 121
Device data collection can be implemented by the Hosted Payment Service on behalf of a merchant. To request
the Hosted Payment Service to implement Kaptcha on your behalf, add the safetech_kaptcha name-value pair to
you request.
A unique session ID is needed to utilize Kaptcha. The session ID is alphanumeric and may be up to 32 characters
in length. This session id is automatically generated when safetech_kaptcha is utilized, unless the request
contains a safetech_kaptcha_id value.
After a session ID is used, it must remain unique for 30 days.
Successful use of the Kaptcha functionality will produce a Chase logo on the page.
Fraud Analysis Requests
Fraud scoring information may be requested on any transaction requested by the Hosted Payment Service. The
hosted_tokenize element may be left empty or set to store_authorize; the store_only value is not supported,
because a transaction is not initiated.
Safetech Fraud Tools are only utilized on transactions which specifically request the service. This is done by
setting the safetech_enable element to ‘true’.
All data elements submitted in an HPP or HPF request are submitted to the Orbital Gateway by the Hosted
Payment Service. The overall value of the fraud score result is directly related to the transaction data included in
the request.
The scope of data returned by the Safetech Fraud Tools is designated by the safetech_format element.
Two Safetech formats are available:
A value of 1 returns the short form fraud analysis information.
A value of 2 returns the long form fraud analysis information. Additional request elements are available, and the
volume of response data is greatly expanded.
Custom Request Data Elements
The Safetech service also allows for additional shopping cart data and/or user defined fields to be passed on a
transaction by transaction basis. These data sets are referred to as “KTT Data”, and may be submitted through
the safetech_ktt_data_string element in the request message.
Page 45 of 121
KTT Data is a collection of name-value pairs. Each name value pair is either a Used Defined Field, or a portion of
shopping cart data. Each User Defined Field or each shopping Cart Data set is pipe delimited (the | character).
Additionally, each User Defined Field or individual element of shopping cart data must be ampersand delimited
(the & character).
Examples of possible User Defined Data are the following:
UPROMOCODE=X6Y3Z1&|UCUSTOMERREFERAL=SocialMedia&|UDISCOUNTGIVEN=10.00&|
Examples of possible shopping card data are the following:
T=Tickets&I=FridayNightBaseballGame&D=SeatsBehindHomePlate&Q=2&P=20000&|
T=StadiumParking&I=FridayNightBaseBallGame&D=VIPParkingPass&Q=1&P=2000&|
Where T=Type; I = Item; D = Description; Q = Quantity; and P = Price. All five sub-elements must be present and
valid, or the fraud analysis fails.
Merchants may submit up to 996 total characters of KTT Data, in whatever combination of User Defined Fields or
Shopping cart data they so choose.
Note: HPP merchants who utilize KTT Data do not need to use any special formatting for delimiters, such as
& or URI encoding. However, any specific value within the KTT Data string which contains a delimiting
character must URI encode that character.
Important:
HPF merchants using KTT data are required to use URI encoding for delimiters. These are %26 for an
ampersand, %3D for an equal sign and %7C for a pipe. However, any specific value within the KTT Data string
which contains a delimiting character must be URI encoded, and the percent sign used to do so must also be URI
encoded as %25.
Example:
• T= StadiumParking
• I = FridayNightGame&PostGameConcert
• D = VIPParking&BackstagePass
• Q=1
• P = 2000
Page 46 of 121
The Safetech service needs to receive the following string from the Hosted payment service (note the delimiting
characters):
T=StadiumParking&I=FridayNightGame%26PostGameConcert&D=VIPParking%26BackstagePass&Q
=1&P=2000&|
For the Hosted Pay Form, using
safetech_ktt_data_string=T%3DStadiumParking%26I%3DFridayNightGame%26PostGameConcert
%26D%3DVIPParking%26BackstagePass%26Q%3D1%26P%3D2000%26%7C
will result in the following (invalid) string going to the Safetech service:
T=StadiumParking&I=FridayNightGame&
The following would produce the intended string:
safetech_ktt_data_string=T%3DStadiumParking%26I%3DFridayNightGame%2526PostGameConce
rt%26D%3DVIPParking%2526BackstagePass%26Q%3D1%26P%3D2000%26%7C
Fraud Analysis Responses
Safetech Fraud Tools is a solution which enables a merchant to better determine the risk involved with a
transaction. The riskScore is a numerical representation of the relative risk of each transaction that is screened.
The information returned can be used to enhance any current risk program, or to develop a customized approach
to risk management.
All response elements related to Safetech Fraud Tools are encapsulated in the safetech_response element of
the applicable HPP or HPF response. The following sub-elements are of particular note:
• The fraudStatusCode provides the status of the request to the Safetech service.
• The autoDecisionResponse provides a high level suggestion of what the riskScore means to the merchant.
 Possible responses are A for Approved, D for Decline, R for Review, E for Manager Review
 Thresholds for each value are configured by the merchant in the Safetech Agent Web Console as part of
a custom fraud analysis strategy.
• The riskScore is a numeric representation of the relative risk of the transaction.
 A numeric value between 1 and 99.
 Higher numbers indicate a higher relative risk.
Page 47 of 121
The Orbital Gateway provides the response information provided by the Safetech service; however it is the
merchant’s decision to proceed or not to proceed with a transaction.
Key items to remember when handling transactions which utilize the Safetech Fraud Tools:
• The authorization returned by the issuer and the safetech_response data from the Safetech service are two
separate and distinct data sets. Example: safetech_response: fraudScoreIndicator:2|fraudStatusCode:X006
• The riskScore or autoDecisionResponse does not impact the Merchant Selectable Response functionality
provided by the Orbital Gateway. Safetech Fraud Tools cannot trigger the Gateway to override an approval with
a decline.
• When a transaction receives a fraud score a merchant deems unacceptable, the merchant should submit a
corresponding Void or Reversal request to the Gateway, before the next End of Day, to prevent the transaction
from going out in settlement.
 Void or Reversal requests are not available through the Hosted Payment Service and must be performed
using a separate API.
Rules Data
Requests to the Safetech service include an element labeled safetech_rulesTrigger. This element in the request
will ask the Safetech Fraud Tools to return the discreet set of rules or validations applied to this transaction.
Information on triggered rules is returned in the rulesData element of the safetech_response data. This element
contains the number of rules triggered, an equal sign, and a comma delimited text string of the individual rules
triggered by the transaction.
An example of this response data is listed below:
0003=1234,338,2974642135
Note: The setup and management of rules is done through the Safetech Agent Web Console.
Additional Notes
The Safetech Fraud Tools support the use of a stand-alone Fraud Analysis message, which requests a fraud
score without performing an authorization.
Merchants who wish to utilize stand-alone Fraud Analysis requests may use the Hosted Payment service to
create a customer profile, and then use that customer profile to submit the stand-alone request to the Orbital
Gateway. This may be done with a separate API or with the Virtual Terminal.
Page 48 of 121
Merchants who request a fraud score as part of their transaction are encouraged to utilize the Kaptcha device
data collector. The safetech_kaptcha element is the suggested way to use this, but merchants may separately
integrate this service into any other page on their website. Ask your Technical Consultant for documentation on
how to do so.
Card Indicators
Card Indicators are authorization data elements available to merchants who utilize the Stratus (BIN 000001)
platform. Card Indicators, also referred to as Card Type Indicators (CTI) are designed to capture valuable data
that helps merchants make better payment decisions – both at the time of the transaction and afterward.
All businesses can identify key data points that can drive payment decisions. Examples of the information
returned by Card Indicators include:
• Affluent cardholders, who generally have no pre-set spending limit.
• Commercial cards, which support level 2 and possibly level 3 data.
• Prepaid cards, which are less likely to support recurring payments.
• Signature Debit cards, which are backed by a checking account of some sort.
• The Country of Issuance is also returned.
Note: Important Card Indicators are intended only for internal use by merchants, and may not be appropriate for
customer consumption. Forced Order Abstraction shields this data from the customer’s browser.
Card Indicator Requests and Responses
Card Indicators are supported for both HPP and HPF integrations. The HPP or HPF requests Card Indicator data
for either of the following two conditions:
• The ‘Card Indicators’ checkbox is selected in the HPS Admin Page in the Virtual Terminal.
• The cardIndicators request element is set to Y.
Note: To override the default setting for a specific transaction, set cardIndicators to N.
Additionally, the following conditions are required for Card Indicators to be returned:
• The merchant’s Orbital Gateway account must be set up on the Stratus platform.
• If present, the hosted_tokenize request element must be set to store_authorize.
Page 49 of 121
The customer must submit a Visa, Mastercard, Discover, Diners, or JCB credit card.
Additional response parameters are present in the HPP response, the HPF Inquiry Response, and/or the HPF
Return XML when this data is returned. Each indicator is returned in a separate element with a ‘Y’ (Yes), ‘N’ (No),
or ‘X’ (Not Applicable or Unknown) value. The country of issuance is returned as a 3 letter ISO country value.
Additional Notes
To request Card Indicators on all transactions through the Hosted Payment Service (HPS), select the Card
Indicators checkbox within the HPS Admin page in the Virtual Terminal.
Caution: Unexpected response parameters can negatively impact merchant integrations to the Hosted Payment
Service. Contact your Technical Implementation Manager before enabling Card Indicators.
Account Verification
Account Verification provides the ability to verify a card-holder’s account without financially impacting their open-
to-buy.
The principle behind Account Verification is that either a zero-value or a one-dollar amount (see below for
difference) is submitted as part of the authorization process, instead of a full transaction amount. This enables the
merchant to verify that the card-holder has provided an active card and that the address information provided is
accurate and aligns to the details held on file by the card-holder’s bank, without reserving funds against the card.
Supported Card Types
• BIN 000001 (Stratus): Visa, Mastercard and American Express
• BIN 000002 (Tandem): Visa, Mastercard, Discover and American Express
As with a standard authorization, both Address Verification Service (AVS) and Card Security Value (CVV) can be
verified along with the account number.
To specifically flag a request for account verification, set the account_verification request parameter to ‘yes’ for
your HPP or HPF request.
Some key points regarding Account Verification messages are:
• hosted_tokenize must be set to ‘store_authorize’
Page 50 of 121
• trans_type must be set to ‘auth_only’
• payment_type must be set to ‘Credit_Card’ or left empty.
• total_amt (HPP) or amount (HPF) is ignored.
• The transaction amount will be zero if the customer submits a Visa or Mastercard.
• The transaction amount will be 1.00 if the customer submits another card type.
• The amount field is not displayed on the page (HPF Only)
A Profile will be returned in the transaction response which should be captured and used to complete the
transaction for the desired amount as per the Customer Profile Management section of this guide.
Stored Credential Framework
Stored Credential Introduction
In addition to generating transactions via cardholder-initiated events, there are also transactions where payment
facilitators need to use a cardholder’s payment credentials (i.e., account details) that were previously stored for
future purchases. A stored credential is information including, but not limited to, an account number or payment
token that is stored by a payment facilitator to process future transactions.
With Stored Credential and Merchant Initiated Transaction Framework, data is presented with authorizations and
transactions to identify stored credentials and indicate cardholder consent was obtained. Within these
frameworks, transactions are presented as either a Cardholder Initiated Transaction (CIT) or a Merchant Initiated
Transaction (MIT). An Orbital API must be leveraged in order to complete MIT transactions. For details regarding
MIT, refer to the applicable Orbital API documentation on Developer Center.
Within this Framework, the merchant is responsible for receiving and retaining the Transaction ID (TXID) for use
on subsequent transactions.
Credential versus Stored Credential
When a credential is used for a single, one-time use, that transaction is considered outside of the Stored
Credential Framework. If a credential is instead used to set up a cardholder account that will support future
purchases, that credential use is considered within the Stored Credential Framework. The initial use of a
credential within the Framework is initiated by the cardholder, and creates a Stored Credential. The Stored
Credential is intended to support more than one transaction.
Page 51 of 121
All Stored Credential transactions must be part of the framework. However, not all credential transactions will
necessarily be part of the framework.
A CIT can be submitted to use a stored credential for a transaction. When initiating a transaction using the
framework, the appropriate message type must be sent. The Comparison of Credentials in Framework table
illustrates the parameters when using both Credentials and Stored Credentials within the framework.
Comparison of Credentials in Framework
Credential (Payment Credential) Stored Credential Within Framework

Within Framework
• First transaction initiated by the • Account (Stored Credential) will be used for future purchases,
cardholder/customer such as card on file, wallet, recurring, etc.
• Can also be used to complete a • Future purchases will use stored information
single transaction or single • Stored Credential can be Payment Token or PAN (Primary
purchase Account Number)
• PAN (Primary Account Number) or • Stored credential can be used by either a cardholder or
Payment Token merchant
• Cardholder disclosure and consent requirements must be

followed
Cardholder-Initiated Transactions
With a Cardholder-Initiated Transaction (CIT), the cardholder/customer performs the transaction. A CIT can be
submitted through a terminal, in a store or an online checkout; available types will vary based on specification
support. A CIT can use payment credentials, which can be a PAN or payment token. A CIT can also use a Stored
Credential.
Typically, an initial CIT is performed using payment credentials to establish an account on file and the Stored
Credential. When a CIT is performed using payment credentials, additional cardholder data such as CVV2 or chip
data (as applicable) is recommended as part of the validation process to demonstrate that the cardholder is
involved in the transaction. Once the account on file is created, the cardholder can also perform CITs using the
Stored Credential.
A CIT can be initiated to complete a purchase or create a stored credential.
Page 52 of 121
• If an amount is due at the time credentials are stored, submit the CIT as an authorization for a purchase
transaction.
• If no amount is due when the credentials are stored, submit the CIT as an Account Verification.
Profiles Managed by Orbital
Orbital maintains stored credential related data on our clients’ behalf. For Visa and Discover profiles, the MIT
(transaction) Type together with the MIT TXID or Network Reference ID (NRID) is stored in the Profile and is
visible to you. MIT TXID/NRID is then used by Orbital to tie subsequent MIT transactions to the initial CIT
Transaction that initiated the CIT sequence. For Mastercard profiles, MIT Types are stored in the profile and will
be visible to merchants.
CIT Profile Creation
Card on file profiles need to use CIT data in order to use the CIT framework for both HPP and HPF.
While initiating a new CIT transaction, create a new profile and store the CIT information on that profile. Orbital
Gateway will use the stored credential information associated with saved profile to complete a CIT framework
transaction. Two parameters are necessary to use the CIT framework:
• The hosted_tokenize parameter is used to identify that a customer profile should be created as part of a
request. Set the hosted_tokenize parameter to store_only to create the profile without submitting for approval,
or set to store_authorize to create the profile while submitting for approval.
• The mitMsgType parameter is used to process the transactions; it indicates the message type code to be used
for the message type records. Set mitMsgType to one of the following:
 CSTO for a Cardholder-Initiated Stored Credential
 CREC for a Cardholder-Initiated Recurring Transaction
 CINS for a Cardholder-Initiated Installment
 CGEN for a Cardholder-Initiated General Transaction
 CEST for a Cardholder-Initiated Estimated Authorization Amount
Page 53 of 121
Message Types for CIT
Message Type Description Card Brands
(mitMstType)
CSTO Cardholder-Initiated Stored Credential Visa
Signifies that the merchant is storing the cardholder credentials for Mastercard
the first time in anticipation of future stored credential transactions. Discover
Example: A cardholder sets up a customer profile for future American Express
purchases.
CREC Cardholder-Initiated Recurring Transaction Visa
Signifies a cardholder initiating the first of a recurring series of Mastercard

transactions. Discover
Example: A cardholder sets up billing for an ongoing monthly gym American Express
membership.
CINS Cardholder-Initiated Installments Visa
Signifies a cardholder initiating the first of a series of installment Mastercard

payments. Discover
Example: A cardholder sets up an agreement with a merchant to American Express
initiate one or more future transactions over a period of time for a
single purchase of a good or service.
CGEN Cardholder-Initiated General Transaction Visa
Signifies cardholder-initiated transactions that can support various Mastercard

merchant-initiated transactions. Discover
Example: A cardholder-initiated authorization that the merchant may American Express
later use to request a re-authorization.
Page 54 of 121
Message Type Description Card Brands
(mitMstType)
CEST Cardholder-Initiated Estimated Authorization Amount Visa
Signifies when an authorization amount is estimated and may not Mastercard

match the completed transaction amount.
Example: Uber uses an estimated authorization to predict the cost

of the trip.
Note: Not supported for American Express or Discover. If an invalid

mitMsgType is attempted, an unsupported Message Type CEST
error will display in HPP, and HPF will return
errorCode=360&gatewayCode=&gatewayMessage=Unsuppor
ted+Message+Type+CEST
Note: Refer to the HPP Request Definitions and HPF Request Definitions for more details regarding parameters.
Page 55 of 121
Orbital Gateway Hosted Payment Hosted Payment Form
HPS Parameters
This chapter provides definitions for the name-value pair elements used by the Hosted Payment Solution.
• Elements which are always required are classified as Mandatory.
• Elements which are only required by certain actions are classified as Conditional.
• Elements which are not required are classified as Optional.
• Fields may be Alpha (A) only, Alphanumeric (AN), or Numeric (N) only.
• Special characters such as pipe characters should generally be URL encoded, while punctuation should not.
Hosted Payment Form
HPF Request Definitions
The Payment Request Form URL Value Descriptions table describes the name-value pairs used in the iFrame request URL.
Payment Request Form URL Value Descriptions
Post Value Description Required Field Type Max Size
hostedSecureID Unique value identifying the client’s Hosted Payment Mandatory AN 32

account.
Note: Lowercase alpha characters only.
Page 56 of 121
hostedSecureAPIToken Unique value associated with Hosted Payment Mandatory AN 32

account
action Tells HPF to create a new payment form Mandatory A 9
Valid value: buildForm
callback_url Sets the URL of the callback.html file. This value Optional AN Varies
overrides the URL set in the Hosted Payment Page
Admin screen.
css_url Sets the URL of the CSS file used to style the payment Optional AN Varies
form.
This value overrides the URL set in the Hosted

Payment Page Admin screen.
allowed_types The card types to display on the payment form. Conditional A Varies
Required unless payment_type = ECP
Valid values:
• American Express
• Diners Club
• Discover
• JCB
• Mastercard
• Visa
Notes: Use a pipe delimiter to append multiple card

types.
Page 57 of 121
payment_type Sets the payment acceptance type. Optional AN 11
Valid values:
• Credit_Card
• ECP
• SAFETECH
Note: If not defined, Credit_Card is default.
trans_type Sets the transaction type for authorization requests. Conditional AN 11
Valid values:
• auth_capture = sets the transaction type to “Sale”
• auth_only = sets the transaction type to “Auth

Only”
Note: Required unless hosted_tokenize = store_only
hosted_tokenize Used to identify if a customer profile should be created Conditional AN 15

as part of a request.
Valid values:
• store_authorize = Create profile while submitting

for approval
• store_only = Create profile without submitting for

approval
See Customer Profile Management
Page 58 of 121
customerRefNum Used in conjunction with hosted_tokenize when the Conditional AN 22

merchant wishes to specify the profile ID of the
customer profile.
amount The total amount of the transaction, including a Conditional N 12

decimal and excluding a currency symbol.
Note: Required unless hosted_tokenize is set to

store_only.
collect_total_amount Displays the total amount field on the payment page. Optional N 1
Valid values:
• 1 = read only
• 2 = editable
Sample code:
<input type=“hidden” name=“collect_total_amount”

value=“1” />
Page 59 of 121
orderId System value of the order or payment. Conditional AN 22
• Field defined and supplied by the auth originator

and echoed back in response.
• The first 8 characters should be unique for each

transaction.
The valid characters include:
• abcdefghijklmnopqrstuvwxyz
• ABCDEFGHIJKLMNOPQRSTUVWXYZ
• 0123456789
• -, $ @ and a space character, though the space

character cannot be the leading character
• PINless Debit transactions can only use

uppercase and lowercase alpha (A-Z, a-z) and
numeric (0-9) characters—NO special characters.

store_only.
order_desc Text description of the purchase Optional AN 64
collect_order_id Display the order id number on the payment page. Optional N 1
Valid values:
• 1 = read only
• 2 = editable
Page 60 of 121
currency_code The three-letter ISO currency displayed with the Optional A 3

amount.
This field must correspond to the currency of the

merchant defined in the Orbital Gateway.
Note: The default for this parameter is USD.
The merchant can use any currency based on their

Orbital account set up.
sessionId Unique session identifier for the customer/user on the Mandatory AN Varies
client site; at least eight characters in length.
analysis Card type and card level options are available. Both Optional AN 20
can be used. Involves BIN lookup to determine P2 or
P3. (Debit or credit)
Valid values:
• card_type = checks debit or credit
• card_level = checks consumer or purchase card
• card_type|card_level = checks both type and level
Page 61 of 121
formType Sets the base layout for the payment form. Optional N 1
Valid values:
• 0 = Short
• 1 = Tall
• 4 = iPhone
• 7 = Div Based
• 9 = ECP tableless
confirm_routing_number Works with formType=9 for ECP. When used, Routing Optional N 1
Number field appears twice for verification on the
payment page.
Valid value = 1
confirm_account_number Works with formType=9 for ECP. When used, Account Optional N 1
Number field appears twice for verification on the
payment page.
Valid value = 1
Page 62 of 121
required Defines which fields on the payment form are required. Optional A 7
Valid values:
• address = address fields are required
• all = all fields required except address fields
• minimum = Card Number and Exp Date required;

Name on Card and CVV optional (default when
blank)
• For ECP transactions, send formtype=9 and

required=all
Note: When omitted, name on card, CVV and address

fields are optional, while card number and expiration
date are required.
collectAddress Sets the option to display billing address fields on the Optional N 1
payment form.
Valid values:
• 0 = Do not display address fields on the payment

form.
• 1 = Display address fields on the payment form.
• 2 = Display address fields including a country field

on the payment form.
• 3 = Collect zip / postal code portion of address

only.
Page 63 of 121
lang Indicates the input fields are presented to the Optional AN 5

consumer in a language other than English.
Valid values:
• en_US = English (default)
• fr_CA = French Canadian
• es_MX = North American Spanish
cardIndicators The transaction should or should not request additional Optional A 1

card product information.
Valid values: Y or N
Note: This value overrides the HPP admin page

default. Stratus (BIN 000001) only.
name Customer name of the billing address Optional AN 30
address Customer street address (billing)–first line Optional AN 30
address2 Customer street address (billing)–second line Optional AN 30
city City of the billing address Optional AN 20
state State or province of the billing address Optional A 2
province State or province of the billing address. Optional AN 2
zip Postal (ZIP) code of the billing address. Optional AN 10
Note: Should be at least five characters in length.
postal_code Postal (ZIP) code of the billing address. Optional AN 10
Note: Should be at least five characters in length.
Page 64 of 121
country ISO code of the country billing address. Two or three Optional A 3
character ISO code (depends on merchant entry).
Default = USA.
customer_id Merchant-generated ID for a specific customer. This Conditional AN Varies

element should only be sent when the
FraudScoreIndicator element is set to 2.
account_verification Transaction should ignore the total_amt and process Optional A 3

an Account Verification instead.
Valid value = yes
max_user_retries Maximum number of times a customer may receive an Optional N 2

error on the hosted pages and be allowed to retry the
transaction.
Example: If set to “2,” then the “Complete” button

changes to “Finished” on the third failed authorization
attempt.
Page 65 of 121
mitMsgType CIT/MIT Message Code Conditional A 4
Indicates the message type code to be used for the

message type records.
Valid values:
• CSTO = Cardholder-Initiated Stored Credential
• CREC = Cardholder-Initiated Recurring

Transaction
• CINS = Cardholder-Initiated Installments
• CGEN = Cardholder-Initiated General Transaction
• CEST = Cardholder-Initiated Estimated

Authorization Amount
mitStoredCredentialInd Stored Credential Flag Conditional A 1
Indicates that the cardholder’s credentials are on-file

with the merchant.
Valid values:
• Blank = null
• Y = Yes
• N = No
Page 66 of 121
mask_type Setting to return the masked PAN on a transaction Optional N 1

response.
Valid values:
• 0 = Last four only (default)
• 1 = First six only
• 2 = First six and last four
csvErrorCodes Setting to return error codes with comma delimiters Optional N 1

instead of pipe delimiters on callback file.
Valid value = 1
safetech_enable Designates the transaction should include a request Conditional A 5

for Fraud Analysis.
Valid values:
• true=Fraud Analysis is requested.
• false=Fraud Analysis is not requested
This element defaults to false.
safetech_format This element directly determines the scope of Conditional N 1

elements returned in the response.
Valid values:
• 1=Short response
• 2=Long response
Page 67 of 121
safetech_rulesTrigger Determines whether the Safetech rules are returned. Optional A 1
Valid values:
• Y=Triggered rules are returned
• N=Triggered rules are not returned
safetech_kaptcha Integrates ‘Kaptcha’ Device Data Collection into the Conditional A 13

Hosted Pay Page on behalf of the merchant.
Valid values:
• enabled
enabledNoLogo
safetech_kaptcha_id A merchant generated session ID for Fraud Analysis Conditional AN 32

performed on this transaction.
See ‘Kaptcha’ Device Data Collection for more

information.
safetech_websiteShortName This value is used by the Safetech service for Fraud Optional A 8
Analysis rules.
safetech_cashValueOfFencibleItems The cash value of any fencible items in the order. Optional N 12
This element is only valid when safetech_format=2.
safetech_customerDriverLicense The customer’s U.S. Driver’s License Number. Optional A 32
safetech_customerID A merchant generated ID for a specific customer. Optional AN 32
Page 68 of 121
safetech_customerIDCreationTime A Unix Epoc format timestamp for the creation of the Optional N 10
value in safetech_customerID.
safetech_ktt_data_string This element can be populated with a string of user- Optional AN 996
defined Fraud Analysis rules, Shopping Cart Data, or
both.
The format of this string is a specialized string of

name-value pairs. See Custom Request Data
Elements for special instructions.
requestSafetechToken This element is used to request a Safetech token for Conditional AN 1

the card to make a payment. Must also send
mitMsgType=CSTO, CREC, CINS, CGEN, CEST.
Valid value = 1
Example of a full transaction posted to the hosted payment form:
hostedSecureID=cpt000000000SB&hostedSecureAPIToken=12345a12b123c1d1e12345f1g12hi1jk&action=buildForm&css_ur
l=https://company.mytestsite.css&callback_url=https://https://companytest.callback.html&sessionId=2e1b7klm7
7fk11id70kl4japr5&payment_type=Credit_Card&allowed_types=Visa|Mastercard|AmericanExpress&analysis=card_type
|card_level&trans_type=auth_only&required=all&formType=1&lang=en_US&collect_total_amount=1&hosted_tokenize=
store_authorize&max_user_retries=3&account_verification=yes&amount=1.00&orderId=hps123456&name=John
Doe&customer_phone=1234567890&address=Apt #123&address2=123 Test
Road&city=BOSTON&state=MA&postal_code=02135&country=US&customer_email=testemail@test.com&customer_id=123456
78
Page 69 of 121
HPF Response Definitions
The Hosted Pay Form returns transaction response data in two separate methods: in a Javascript Object
Notation (JSON) response sent through the customer’s browser and in an XML file directly to the
merchant’s server. This allows both customer–facing and merchant–facing responses to be handled as a
merchant sees fit.
Customer–Facing Response Handling
Post Messaging Functions
• hpfReady()
This function is called when HPF has finished loading and ready for user input.
• startPayment()
When the user clicks the Submit button, this function is triggered.
• cancelPayment()
This function triggers when the user cancels the payment by clicking the cancel button.
• handlePaymentErrors()
This function is called when the customer submits data that does not pass form validation or the
credit card does not process as expected. This function returns a single object containing a list of
error codes, the gateway code and message rather than a pipe delimited string of error codes. Refer
to Appendix A for a list of error codes.
For example, the following error displays multiple error values:
Error: 360,((841)),Error validating card/account number range
• completePayment()
This function is called when a transaction processed successfully.
• scrollRelay()
When a user scrolls over the payment form, this function relays the X and Y coordinates of each
scroll event in the iframe.
Page 70 of 121
Callback Functions
Customer-facing responses are handled in functions contained in the Callback page of the HPF
implementation. Those functions are listed below:
• cancelCREPayment()
 Called when the customer clicks the cancel button on the payment form
 Function closes the iFrame and indicates that the customer’s card was not charged
• whatCVV2()
 Called when the customer clicks the link for more information about CVV2 numbers
 Function displays a popup window, which describes what the CVV2 number is and where to find
it on the card
• completeCREPayment(transaction)
 Called when a transaction is processed successfully
• creHandleDetailErrors(errorCode, gatewayCode, gatewayMessage)
 Optionally called for transaction errors when more detailed information is required for debugging
Note: Transaction responses are also sent directly to the merchant in an XML format. See HPF
Response on the Return URL for more details.
• creHandleErrors(errorCode)
This function is called when the customer submits data that does not pass form validation or the
credit card does not process as expected.
The errorCode parameter is a pipe-delimited string containing three-digit error codes that correspond
to the errors that occurred. Possible error responses are listed in Appendix A: Error Handling.
• creHandleDetailErrors(errorCode, gatewayCode, gatewayMessage)
This function is a more detailed version of CREHandleErrors, for situations where more detailed
debugging information is required.
The parameters report information about the errors as described below:
Page 71 of 121
 errorCode = A pipe delimited string of three-digit error codes returned specifically by the Hosted
Payment service. Possible error responses are listed in Appendix A: Error Handling.
 gatewayCode = The proc status code returned by the Orbital Gateway. These are common
response messages to all Orbital Gateway interfaces.
 gatewayMessage = The proc status text reported by the Orbital Gateway for the transaction.
These are common response messages to all Orbital Gateway interfaces.
 completeCREPayment(transaction) = This function is called when a transaction is processed

successfully. The transaction parameter is a JSON object that is returned on the callback file and
contains the following information:
HPF JSON Response on the Callback File

After the transaction is complete, response data is returned to the customer browser and (optionally) the
merchant. The response echoes the uID, returns the transaction status, and suppresses all other
response elements.
Parameter Name Description Max Size
code Success or failure code. See Appendix A: Error Handling for Varies
details.
message Contains the transaction response message. If the Varies

transaction fails, an error message is returned. If the
transaction is successful, “Success” is returned.
uID Contains the unique value used to identify the transaction Varies
requested.
rurl Hosted Payment Solution endpoint used to submit the HPF Varies
request.
Does not include full request parameters.
Customize the display of error messages and transaction responses by editing the Merchant-Facing
Response Handling.
Page 72 of 121
Merchant-Facing Response Handling
Your server may retrieve the suppressed elements by submitting a query request as an HTTPS GET to
the specified hosted payment service address. The transaction results associated with the uID token are
queried, and response data is returned to your server for response handling.
HPF Response on a uID Query
Max
Parameter Name Description
Size
hostedSecureID Hosted Payment account used to request the transaction. 32
hostedSecureAPIToken Hosted API Token associated to Hosted Payment account 32

used to request the transaction.
uID Unique value identifying the transaction returned by the HPS 32

System
uIDTrans When transaction is processed using Order Abstraction. 1
Valid value: 1
order_id System value of the order or payment. 22
details.
error If an error is returned, this value = “1” 1
message Contains the transaction response message. If the Varies

transaction fails, an error message is returned. If the
transaction is successful, “Success” is returned.
mPAN Masked card or checking account number collected. (15-19) 19
name Cardholder name collected. Varies
type Card brand type, auto detected based on the starting Varies
number or BIN Range.
card_brand_selected Card brand selected by the customer. Varies
exp Card brand expiration date (month and year). 4
total_amt Transaction amount. 12
AVSMatch Gateway response for Address Verification Matching. Varies
CVVMatch Gateway response for CVV matching. Varies
Page 73 of 121
Max
Size
TxnGUID Transaction ID returned by the gateway. Varies
ApprovalCode Approval code for the transaction. Varies
transType Transaction type for authorization requests. 12
trans_type Transaction type for authorization requests. 12
customerRefNum Customer Profile ID returned by the gateway. 22
callback_url Callback file URL used in the uID init request. Varies
css_url CSS URL file URL used in the uID init request. Varies
user_agent Browser used to process the transaction. Varies
analysis_result Card type and card level analysis response. Varies
Transaction type. Possible values "Credit_Card," "ECP," 11

payment_type
"SAFETECH"
customer_phone Phone number for the billing address (10-14 digits). 14
postal_code Postal code for the billing address (5-10 char). 10
customer_email Customer email for the billing address. 50
customer_id Merchant-generated ID for a specific customer. Varies
customer_address Customer street address (billing) –first line. 30
customer_address2 Customer street address (billing) –second line. 30
customer_city City of the billing address. 20
customer_state State or province of the billing address 2
ISO code of the country billing address. Two or three 3

customer_country character ISO code (depends on merchant entry). Default =
USA.
mitMsgType MIT message type passed in the request. 4
mitStoredCredentialInd MIT stored credential flag. 1
mitReceivedTransactionID The received Transaction ID returned to the merchant. 15

Always present for CIT/MIT transactions.
profileProcStatus Value indicating the success or failure of the profile portion Varies
of a store_authorize or store_only request.
profileProcStatusMsg Text explanation of the profileProcStatus value. Varies
Page 74 of 121
Max
Size
profileId Hosted Payment account used to request the transaction. 32
total_amt Total amount of the transaction. 12
order_id System value of the order or payment. 22
safetech_response A URI-encoded, delimited list of all response elements Varies

returned by the Safetech service.
Each response element is delimited with a pipe.
Each response element uses this format:

element_name:element_value
Sub-elements include:
fraudScoreIndicator=the safetech_format value
fraudStatusCode=Safetech response code.
riskInquiryTransactionID=Unique Fraud Analysis ID
autoDecisionResponse=The following is a list of valid

values:
• A=Approved
• D=Decline
• E=Manager Review
• R=Review
riskScore=The Fraud Score. 1-99, higher number has more

risk
kaptchaMatchFlag=was Kaptcha successful?
*worstCountry=ISO 3166 highest risk country associated to

the customer
*customerRegion=lower = state, UPPER= country.
*paymentBrand=The payment method (brand) identified by

the Safetech service during Fraud Analysis. This element is
only returned with a Fraud Score Indicator of 2.
*fourteenDayVelocity=number of sales to customer in 14

days
*sixHourVelocity=number of sales to customer in 6 hours.
Page 75 of 121
Max
Size
*customerNetwork=type of physical network used
*numberOfDevices=# of devices associated to customer
*numberOfCards=# of cards associated to customer
*numberOfEmails=# of emails associated to customer
*deviceLayers=delimited string of device data.
*deviceFingerprint=a unique hash of system identifiers
*customerTimeZone=current time zone of customer
*customerLocalDateTime=current local time of customer
*deviceRegion=lower = state, UPPER= county.
*deviceCountry=ISO 3166 where the device resides
*proxyStatus=indicates if customer is on proxy network
*javascriptStatus=indicates if customer uses javascript
*flashStatus=indicates if customer uses flash
*cookiesStatus=indicates if customer allows cookies
*browserCountry=ISO 3166 where the browser resides
*browserLanguage=ISO 639-1 language of customer

browser
*mobileDeviceIndicator=is the customer on a mobile

device?
*mobileDeviceType=description of the mobile device
*mobileWirelessIndicator=is the device wireless capable?
*voiceDevice=is the device voice controlled?
*pcRemoteIndicator=is the user remotely using the PC?
rulesDataLength=length of rulesData string
rulesData=URI encoded, comma delimited list of rules

triggered by the transaction
*Returned only if safetech_format=2
ctiAffluentCard Card Indicator: Affluent Category 1
Affluent cards may have very high or no pre-set spending

limit.
Page 76 of 121
Max
Size
All Card Indicators can return Y (Yes), N (No) or X (Not

Applicable or Unknown). See Card Indicators for more
information.
ctiCommercialCard Card Indicator: Commercial Card 1
ctiDurbinExemption Card Indicator: Durbin 1
ctiHealthcareCard Card Indicator: Healthcare Card 1
ctiLevel3Eligible Card Indicator: Level 3 Data Eligibility 1
ctiPayrollCard Card Indicator: Payroll Card 1
ctiPrepaidCard Card Indicator: Prepaid Card 1
ctiPINlessDebitCard Card Indicator: PINless Debit Eligibility 1
ctiSignatureDebitCard Card Indicator: Signature Debit Eligibility 1
ctiIssuingCountry Card Indicator: Issuing Country 3
Returns a 3 letter ISO country code
safetechToken Safetech Token returned 19
HPF Response on the Return URL

The Orbital Gateway returns an XML message to the Return URL set in the merchant’s Hosted Pay Page
Admin screen. The table describes the values returned in the XML document.
The return URL is not used for handling responses in HPF. Its only purpose is to provide additional
information for database insertion or as a secondary validation of a transaction result. The return file
information is not available in real time and may take several minutes to populate.
Parameter Name Description Max

Size
transactionStart Transaction start time (UNIX) 10
transactionEnd Transaction end time (UNIX) 10
orderId System value of the order or payment. 22
sessionId Unique session identifier for the customer/user on the Varies

client site; at least eight characters in length.
Page 77 of 121

Size
status Status code of the transaction. 3
transId Null 0
approvalCode Approval code for the transaction. Varies
tokenId Token associated to Hosted Payment account used to 32

request the transaction.
amount Total amount of the transaction. 12
name Cardholder name collected Varies
customerId Merchant-generated ID for a specific customer. Varies
customerEmail Customer email for the billing address. 50
cardNumber Masked credit card number. 16
cardType Credit card type(s) accepted. Varies
cardBrandSelected Contains the payment association for the selected card. Varies
expMonth Expiration month. 2
expYear Expiration year. 4
uID Unique value identifying the transaction returned by the 32

HPS System
profileProcStatus Value indicating the success or failure of the profile Varies

portion of a store_authorize or store_only request.
profileId Hosted Payment account used to request the transaction. 32

This field will always have a value for CIT/MIT
transactions.


Page 78 of 121

Size

autoDecisionResponse=The following is a list of
valid values.
• A=Approved
• D=Decline
• R=Review
riskScore=The Fraud Score. 1-99, higher number has

more risk
*worstCountry=ISO 3166 highest risk country

associated to the customer
*paymentBrand=The payment method (brand) identified

by the Safetech service during Fraud Analysis. This
element is only returned with a Fraud Score Indicator of
2.
*fourteenDayVelocity=number of sales to customer in

14 days
*sixHourVelocity=number of sales to customer in 6

hours.
Page 79 of 121

Size
*customerLocalDateTime=current local time of

customer

browser

device?
*mobileWirelessIndicator=is the device wireless

capable?

Affluent cards may have very high or no pre-set spending

limit.

information.
Page 80 of 121

Size
Notes:
• The HPF only returns a merchant-facing response when a transaction is successful. In the event of a
failed payment, the customer is shown the payment form again with an error message. The customer
can either correct the form and retry the transaction or leave the page.
• Response parameters are not guaranteed to appear in the order they are documented. Responses may
contain deprecated response elements, which should be ignored. This is more likely if a previous “Orbital
Hosted Payment Specification” value has been selected in your Virtual Terminal HPP Admin Page.
Refer to Appendix C: Hosted Payment Admin for more information.
Page 81 of 121
Orbital Gateway Hosted Payment Hosted Payment Page
Hosted Payment Page
HPP Request Definitions
The values in the Payment Request Page Post Value Descriptions table are used in a call to the Hosted Payment Page service.
Payment Request Page Post Value Descriptions
Post Value Description Required Field Type Max

Size
hostedSecureID Unique value identifying the client’s Hosted Payment Mandatory AN 32

account.
Note: Lowercase alpha characters only.
hostedSecureAPIToken Unique value associated with Hosted Payment account Mandatory AN 32
content_template_url URL where the merchant template resides – must be https Mandatory AN Varies
accessible
return_url URL on the merchant site where the customer is returned, Mandatory AN Varies
along with the values from a successful transaction; must
be https accessible.
Note: If a customer remains on the payment page for

more than 15 minutes, HPP returns the customer to the
return_url with the action parameter with the value
“Cancel.”
Page 82 of 121

Size
cancel_url URL on the merchant site where the customer is returned Optional AN Varies
if the customer clicks “Cancel” on the payment form; must
be https accessible. If not defined, HPP returns the
customer to the URL set by the return_url post value.
allowed_types Card types to display on the payment form. Conditional A Varies
Valid values:
• American Express
• Diners Club
• Discover
• JCB
• Mastercard
• Visa
Notes: Use a pipe delimiter to append multiple card types.
Required unless payment_type = ECP
payment_type Sets the payment acceptance type. Conditional AN 11
Valid values:
• Credit_Card (default)
• ECP
• SAFETECH
Required with Account Verification functionality.
Page 83 of 121

Size
trans_type Sets the transaction type for authorization requests. Conditional AN 12
Valid values:
• auth_capture = sets the transaction type to “Sale”
• auth_only = sets the transaction type to “Auth Only”

“store_only”
hosted_tokenize Used to identify if a customer profile should be created as Conditional AN 15

part of a request.
Valid values:
• store_authorize = Create profile while submitting for

approval
• store_only = Create profile without submitting for

approval
See Customer Profile Management
customerRefNum Used in conjunction with hosted_tokenize when the client Conditional AN 22

wishes to specify the profile ID of the customer profile.
total_amt Total amount of the transaction, including a decimal and Conditional N 12

excluding a currency symbol.

store_only.
Page 84 of 121

Size
collect_total_amount Displays the total amount field on the payment page Optional N 1
Valid values:
• 1 = read only
• 2 = editable
Sample code:
<input type=“hidden” name=“collect_total_amount”

value=“1” />
order_id System value of the order or payment. Conditional AN 22

store_only.
order_desc Text description of the purchase. Optional AN 64
Note: Where applicable, this field falls under “Customer

Defined Data” in online merchant reporting tools.
collect_order_id Display the order id number on the payment page. Optional N 1
Valid values:
• 1 = read only
• 2 = editable
Page 85 of 121

Size
currency_code The three-letter ISO currency displayed with the amount. Optional A 3
This field must correspond to the currency of the merchant

defined in the Orbital Gateway.
Note: The default for this parameter is USD.
The merchant can use any currency based on their

Orbital account set up.
sess_name Used in conjunction with the session ID to pass a session Conditional AN Varies
variable to the client payment template.
Note: sess_name (former portion) and sess_id combine to

form a name-value pair.
sess_id Used in conjunction with the session name to pass a Conditional AN Varies
session variable to the client payment template.
Note: sess_name and sess_id (latter portion) combine to

form a name-value pair.
analysis Card type and card level options are available. Both can Optional AN 20
be used. Involves BIN lookup to determine P2 or P3.
(Debit or credit)
Valid values:
• card_type = checks debit or credit
• card_level = checks consumer or purchase card
• card_type|card_level = checks both type and level
Page 86 of 121

Size
form Sets the base layout for the payment form. Optional AN 13
Valid values:
• osc = OS Commerce style
• mage = Magento style form
• mobile_first = Responsive Form type using bootstrap
• tableless = single column tableless ADA compliant

form
• ecp_tableless = single column tableless for ECP

payment type
confirm_routing_number Works with form = ecp_tableless for ECP. When used, Optional N 1
Routing Number field appears twice for verification on the
payment page.
Valid value = 1
confirm_account_number Works with form = ecp_tableless for ECP. When used, Optional N 1
Account Number field appears twice for verification on the
payment page.
Valid value = 1
Page 87 of 121

Size
button_label Works with form = tableless. Settings to change Submit Optional N 1

button label for tableless form.
Valid values:
• 0 = “Submit” (default)
• 1 = “Pay $ {Amount} “
• 2 = “Pay”
• 3 = “Pay Now”
• 4 = “Complete”
required Defines which fields on the payment form are required. Optional A 7
Valid values:
• address = address fields are required
• all = all fields required except address fields
• minimum = Card number and expiration date required;

name on card and CVV optional (default when blank)
• For ECP transactions, send formtype=9 and

required=all
Note: When omitted, name on card, CVV and address

fields are optional, while card number and expiration date
are required.
Page 88 of 121

Size
collectAddress Sets the option to display billing address fields on the Optional N 1
payment page.
Valid values:
• 0 = Do not display address fields on the payment

page.
• 1 = Display address fields on the payment page.
• 2 = Display address fields including a country field on

the payment page.
• 3 = Collect zip/postal code portion of address only.
Note: When the payment_type value ECP is submitted

and the integration type is HPF the collectAddress function
automatically disables.
lang Indicates the input fields are presented to the consumer in Optional AN 5
a language other than English.
Valid values:
• en_US = English (default)
• fr_CA = French Canadian
• es_MX = North American Spanish
Page 89 of 121

Size
cardIndicators The transaction should or should not request additional Optional A 1

card product information.
Valid values: Y or N
Note: This value overrides the HPP admin page default.

Stratus only.
customer_firstname Customer first name Optional AN 30
customer_lastname Customer last name Optional AN 30
customer_address Customer street address (billing)–first line Optional AN 30
customer_address2 Customer street address (billing)–second line Optional AN 30
customer_city City of the billing address Optional AN 20
customer_state State or province of the billing address Optional A 2
customer_postal_code Postal (ZIP) code of the billing address; at least five Optional AN 10
characters in length.
customer_country ISO code of the country billing address. Two or three Optional A 3
character ISO code (depends on merchant entry). Default
= USA.
customer_id Merchant-generated ID for a specific customer. This Conditional AN Varies

element should only be sent when the
FraudScoreIndicator element is set to 2.
customer_company Customer company name Optional AN 32
customer_email Customer email for the billing address; must follow valid Optional AN 50
email formatting
Page 90 of 121

Size
customer_phone Phone number for the billing address. Optional N 14
Note: Should be at least 10 characters in length.
account_verification Transaction should ignore the total_amt and process an Optional A 3

Account Verification instead.
Valid value = yes
max_user_retries Maximum number of times a customer may receive an Optional N 2

transaction.
Example: If set to “2,” then the shopper will be redirected

to the client’s return_url on the third failed authorization
attempt.
processing_overlay Setting to display a visual element on the payment page Optional N 1

that indicates the transaction is processing.
Valid value = 1
Page 91 of 121

Size
mitMsgType CIT/MIT Message Code Conditional A 4
Indicates the message type code to be used for the

message type records.
Valid values:
• CSTO = Cardholder-Initiated Stored Credential
• CREC = Cardholder-Initiated Recurring Transaction
• CINS = Cardholder-Initiated Installments
• CGEN = Cardholder-Initiated General Transaction
• CEST = Cardholder-Initiated Estimated Authorization

Amount
mitStoredCredentialInd Stored Credential Flag Conditional A 1
Indicates that the cardholder’s credentials are on-file with

the merchant.
Valid values:
• Blank = null
• Y = Yes
• N = No
Page 92 of 121

Size
mask_type Setting to return the masked PAN on a transaction Optional N 1

response.
Valid values:
• 0 = Last four only (default)
• 1 = First six only
• 2 = First six and last four
safetech_enable Designates the transaction should include a request for Conditional A 5

Fraud Analysis.
Valid values:
• true=Fraud Analysis is requested.
• false=Fraud Analysis is not requested
This element defaults to false.
safetech_format This element directly determines the scope of elements Conditional N 1

returned in the response.
Valid values:
• 1=Short response
• 2=Long response
Page 93 of 121

Size
safetech_rulesTrigger Determines whether the Safetech rules are returned. Optional A 1
Valid values:
• Y=Triggered rules are returned
• N=Triggered rules are not returned
safetech_kaptcha Integrates ‘Kaptcha’ Device Data Collection into the Conditional A 13

Hosted Pay Page on behalf of the merchant.
Valid values:
• enabled
• enabledNoLogo
safetech_kaptcha_id A merchant generated session ID for Fraud Analysis Conditional AN 32

performed on this transaction.
See ‘Kaptcha’ Device Data Collection for more

information.
safetech_websiteShortName This value is used by the Safetech service for Fraud Optional A 8
Analysis rules.
safetech_cashValueOfFencibleItems The cash value of any fencible items in the order. Optional N 12
safetech_customerDriverLicense The customer’s U.S. Driver’s License Number. Optional A 32
safetech_customerID A merchant generated ID for a specific customer. Optional AN 32
Page 94 of 121

Size
safetech_customerIDCreationTime A Unix Epoc format timestamp for the creation of the value Optional N 10
in safetech_customerID.
safetech_ktt_data_string This element can be populated with a string of user- Optional AN 996
defined Fraud Analysis rules, Shopping Cart Data, or both.
The format of this string is a specialized string of name-

value pairs. See Custom Request Data Elements for
special instructions.
requestSafetechToken This element is used to request a Safetech token for the Conditional AN 1
card to make a payment. Must also send mitMsgType=
CSTO, CREC, CINS, CGEN, CEST
Valid value = 1
Example of Hosted Payment Page transaction request:
hostedSecureID=cpt0000000SB&hostedSecureAPIToken=12345a12b123c1d1e12345f1g12hi1jk&action=buildForm&content_
template_url=https://www.website.com/hpptemplate.html&return_url=https://companytest.return.html&cancel_url
=https://companytest.cancel.html&allowed_types=Visa|Mastercard&trans_type=auth_only&processing_overlay=1&co
llectAddress=1&hosted_tokenize=store_authorize&total_amt=1.00&order_id=hps123456
Page 95 of 121
Orbital Gateway Hosted Payment HPS Parameters
HPP Response Definitions
After the payment transaction is complete, the customer is connected directly back to the Transaction
Success Response page on your website. The response is returned as name/value pairs in an HTTP
$_GET (postback) to the supplied return URL.
HPP Response Data on the Return URL
Max
Size
details.
message Contains the error message if an error is returned. Varies
uID Contains the unique value used to identify the transaction 32

requested.
action Indicates the transaction was not completed. Returned if Varies

max_user_retries is exceeded.
Valid values:
cancel = customer canceled the transaction or it has timed out
attemptsExceeded = customer received a decline or error more

times than the max_user_retries request element allows.
Page 96 of 121
HPP Response Data on a uID Query
Max
Size
hostedSecureAPIToken Hosted API Token associated to Hosted Payment account 32

used to request the transaction.
uID Contains the unique value used to identify the transaction 32

requested.
uIDTrans When transaction is processed using Order Abstraction. 1
Valid value: 1
order_id Order ID passed in the transaction. 22
code Success or failure code. See Appendix A: Error Handling Varies

for details.
error If an error is returned, this value = “1” 1
message Contains the error message if an error is returned. Varies
mPAN Masked card or checking account number collected. (15- 19

19)
name Cardholder name collected. 60
customer_firstname Cardholder first name collected. Varies
customer_lastname Cardholder last name collected. Varies
type Card brand type, auto detected based on the starting Varies
number or BIN Range.
exp Card brand expiration date. 4
total_amt Transaction amount. 12
card_brand_selected Card brand selected by the customer. Varies
TxnGUID Transaction ID returned from the gateway. Varies
ApprovalCode Approval code for the transaction. Varies
transType Transaction type for authorization requests. 12
Page 97 of 121
Max
Size
customerRefNum Customer Profile ID returned by the gateway. 22
profileProcStatus Value indicating the success or failure of the profile portion Varies
of a store_authorize or store_only request.
content_template_url Content template page URL used in the request. Varies
return_url Return URL used in the request. Varies
cancel_url Cancel URL if used. Varies
user_agent Browser used to process the transaction. Varies
analysis_result Card type and card level analysis response. Varies
max_user_retries Maximum number of times a customer may receive an 2

transaction.
hosted_tokenize Indicates that a customer profile was created as part of a 15

request.
account_verification Indicates that a transaction ignored the total_amt and 3

processed an Account Verification instead.
mitMsgType Indicates the CIT message type code to be used for the 4
message type records
mitStoredCredentialInd Indicates that the cardholder’s credentials are on-file with 1

the merchant

This field will always have a value for CIT/MIT
transactions.


Page 98 of 121
Max
Size
autoDecisionResponse=The following is a list of valid

values.
• A=Approved
• D=Decline
• R=Review
riskScore=The Fraud Score. 1-99, higher number has

more risk
*worstCountry=ISO 3166 highest risk country associated

to the customer
*paymentBrand=The payment method (brand) identified

by the Safetech service during Fraud Analysis. This
element is only returned with a Fraud Score Indicator of 2.
*fourteenDayVelocity=number of sales to customer in 14

days
*sixHourVelocity=number of sales to customer in 6 hours.
*customerLocalDateTime=current local time of customer
Page 99 of 121
Max
Size

browser

device?
*mobileWirelessIndicator=is the device wireless

capable?


Affluent cards may have very high or no pre-set spending limit.
information.
Page 100 of 121

Max
Size
Page 101 of 121

Orbital Gateway Hosted Payment Frequently Asked Questions
Frequently Asked Questions

This chapter covers common questions or concerns related to the use and implementation of the Hosted
Payment service. Contact the merchant Chase Merchant Services Analyst or Account Executive for more
information.
1. Why do I see a page I did not design with the words “[[FORM INSERT]]?”
The template file is fetched in real time, every time an HPP request is made to the Hosted Payment
Solution. The service must be given a valid, https accessible URL to fetch the template.
2. Why do I receive the error “Issue 10034-2351 has been encountered?”
The service returns this error when a template URL is provided, but the process of fetching the
template fails. See the issue description for 10034-2351 in the Integration Error table located in
Appendix A: Error Handling for more information.
3. Why are separate, direct integration points helpful?
Separate, direct integration points are helpful to perform actions that are not supported by the Hosted
Payment Solution. For example, HPS can create Orbital profiles, but does not process requests that
use the profiles. Clients need a separate integration to one of the Orbital APIs or need to utilize
Orbital Virtual Terminal in order to process requests that use profiles.
4. When is the hostedSecureAPIToken used?
The hostedSecureAPIToken is used to engage the service to generate the uID prior to displaying
the form/page for payment. The value is not visible to the end user. The only Order Abstraction
scenarios that require the use of this value are initial uID generation and uID response query.
The hostedSecureAPIToken is meant to remain secret to everyone but the client and the server.
This name-value pair should only be submitted to the Order Abstraction endpoints, and should never
be submitted to the standard HPP/HPF endpoints.
5. How does the collectAddress request element interact with my request parameters?
The collectAddress request element gives customers the ability to input a billing address in the form
fields provided by the HPP or HPF. A valid billing address is required when collectAddress is
utilized. U.S. addresses (including Armed Forces) and International addresses are supported, based
on the collectAddress value.
Page 102 of 121

Billing address details are also supported using request parameters for each address field (i.e.,
customer_address, customer_city, customer_state, customer_zip). These details are passed as-
is to the issuer when collectAddress is off, and they pre-fill the HPP or HPF address form when
collectAddress is used.
6. Why does my HPP implementation display with broken content, such as images?
A common mistake when working with HPP is to forget the “base” HTML element, which is used in
the template page to resolve content such as images.
Example: <base href=https://www.example.com/>
7. Why do the action buttons in my HPP implementation resolve to broken links?
The template forms the base of the Hosted Payment Page, and the payment fields are woven where
the service finds a [[FORM INSERT]] string. If this string is located within a wrapper with a relative
URL, such as a Form or DIV, the payment links can be misdirected to relative links which do not exist.
8. Why do the action buttons in my HPF implementation seem to be unresponsive?
The parent page contains response functions, and the buttons on the page can trigger those
functions. Response data is fed from the iFrame to the parent page via the callback file.
A number of scenarios may impede this flow of information:
 The parent page must contain response functions to take action on a transaction.
 If the web browser does not contain the correct domain, the browser prevents data flow between
iFrame and parent page, including any prefixes, such as “www.”
 The callback file must be available to the Hosted Payment service. To test this, place the exact
callback URL in a web browser and confirm the page can be found.
9. Why do I receive the error, “No Validation domains found?”
The most common reason for this error is when an HPP merchant has not listed any authorized
domains in the HPP Admin Settings in the Virtual Terminal, or when the HPP parameters are
submitted as a GET instead of a POST.
This error can also be triggered when the service cannot find a valid secure account ID in the request.
This is most likely due to an incorrectly encoded uID in the initial request.
Page 103 of 121

Validate the secure account ID name-value pair is correct in the merchant uID request; the name is
case sensitive and the value will never be a merchant number nor a Virtual Terminal username.
Depending on the merchant environment, contact Gateway Support or the merchant Analyst for
further details.
Page 104 of 121

Orbital Gateway Hosted Payment Appendix A: Error Handling
Appendix A: Error Handling

There are three categories of errors that can occur with the Hosted Payment Solution:
1. Integration errors
2. Pre-fail errors
3. Orbital Gateway errors
Integration Errors
Integration errors can occur if there are issues integrating the HPS system into the merchant application.
Error Occurs in Description
Issue 10034-2351 has been HPP The service returns this error when a template URL
encountered is provided, but the process of fetching the template
fails. Possible triggers include:
• Server has an invalid SSL/TLS certificate, a self-

signed cert or using a cipher that is not
supported. Ensure cert is properly installed from
a trusted authority and enable TLSv1.2 support.
• Template URL is unreachable or incorrect.

Ensure the template exists and the URL is
correct. Example:
<input type="hidden"
name="content_template_url"
value="REPLACE WITH YOUR CONTENT
TEMPLATE PAGE URL HERE" />
• Access to the merchant implementation might
not be possible. This is usually related to a
firewall that is blocking our servers from
communicating directly with the merchant
servers. IP addresses need to be added to the
merchant firewall allow list. Refer to IP
Addresses.
Page 105 of 121

Error Occurs in Description
Issue 10034-2356 has been HPP Often occurs after issue 10034-2351 has been
encountered cleared. See description above.
Domain validation check failed for HPP This error occurs when the domain sending the
https://www.example.com HTTPS form POST is not entered into the
Authorized Websites list in a merchant's profile.
Ensure the domains are entered without spaces or
carriage returns and no "http://" or “https://.”
Example: domain1,domain2,domain3.
Note: If the domain requesting the transaction exists

in the Authorized Websites list and the merchant still
receives the same error, then work with the
merchant hosting/networking team to correct any
possible Routing/NATing issues.
Store profile is incomplete … HPF This error means your profile is missing some
aborting! required information. This error typically occurs when
the following HPF URLs are missing in your profile
configuration:
• CSS URL
• Return URL
• Callback URL
Verify your profile and insert all the required

information before proceeding to the merchant
integration.
Missing or unknown profile HPP and This error occurs if the merchant is using an
HPF incorrect hostedSecureID or endpoints in the
integration.
Ensure the correct hostedSecureID is passed to the

endpoints URL.
TEXT_ERROR_HPF_MERCHANT HPP and Parameter names and values are case sensitive,
_ID_MISSING HPF and they are different according to the integration
method such as HPP or HPF.
Ensure correct parameters are passed to the

merchant integration code.
Page 106 of 121

Pre-Fail Errors
Pre-fail errors can occur if a transaction fails prior to submission to HPS. This typically indicates the built–
in validation found an error and did not submit the transaction for processing. See the Hosted Payment
Specific Response Codes table.
In HPF, only the error response codes are returned (see Response Code column). The message
descriptions can be customized according to the error code on the merchant system.
In HPP, message descriptions are returned and can appear on the page or as pop-ups on the screen
(see the Description column).
Hosted Payment Specific Response Codes
Response Description
Code
000 Successful request.
100 Merchant Identifier left blank or not valid. The transaction was not processed.
110 Session Identifier left blank. The transaction was not processed.
118 Too many CAPTCHA retries.
200 Name not present.
300 Amount not specified or invalid value entered
310 Credit card number left blank or did not pass Mod10.
315 Credit card number did not pass Mod10.
320 Credit card type left blank or invalid.
330 Expiration month left blank.
340 Expiration year left blank.
350 CVV2 field submitted but does not match the card.
355 CVV2 required but not present.
357 An invalid character was entered, such as a letter in a numeric field.
360 Payment declined by financial institution, or some other error has occurred (returned
from Orbital), such as an invalid message type.
365 The max_user_retries limit has been reached.
Page 107 of 121

Response Description
Code
370 Expiration date invalid.
400 Transaction tracer value does not match.
500 Address one field required but left blank.
510 City field required but left blank.
520 State field required but left blank.
530 ZIP/postal code field required but left blank.
531 Invalid ZIP/postal code format received.
550 Country is missing.
600 Bank name was blank (ECP Only).
610 Routing Number is blank (ECP Only).
620 Checking Account number was blank (ECP Only)
630 Routing Number is invalid (ECP Only)

• HPS may return additional error codes when 360 is returned
• Also refer to Common Orbital Error Messages table
640 Routing Number is invalid (ECP Only)
Orbital Gateway Errors

The errors that display with double parenthesis ((0)) are returned by the Orbital Gateway. Refer to the
applicable Orbital API specification located in Developer Center for more details regarding error
messages if not found in the following Common Orbital Gateway Error Messages table.
The following table contains the most common Orbital Gateway interface error codes.
Page 108 of 121

Common Orbital Gateway Error Messages
Error Code Description
05 Do Not Honor
52 Processor Decline
89 Credit Floor
521 Transaction Data is badly formatted.
841 Account number has failed a prefix check and is invalid for the merchant account
20412 Security information is not configured
9582 Cannot create profile=Profile ID already exists
Page 109 of 121

Orbital Gateway Hosted Payment Appendix B: Payment Form CSS Classes
Appendix B: Payment Form CSS Classes

The table describes the CSS classes that apply to the payment form.
Form Class Name Description

Type(s)
0,1,5 body Body of the containing iFrame.
0,1 .mainTable Table containing form elements.
0,1 .creNameRow TR containing the name elements.
0,1 .creNameLabel TD containing the name label.
0,1 .creNameField Input containing the name parameter.
0,1 .creAddressOneRow TR containing the ‘first address’ elements.
0,1 .creAddressOneLabel TD containing the first address label.
0,1 .creAddressOneField Input containing the address one parameter.
0,1 .creAddressTwoRow TR containing the ‘second address’ elements.
0,1 .creAddressTwoLabel TD containing the second address label.
0,1 .creAddressTwoField Input containing the address two parameter.
0,1 .creCityRow TR containing the city elements.
0,1 .creCityLabel TD containing the city label.
0,1 .creCityField Input containing the city parameter.
0,1 .creStateZipRow TR containing the ZIP/postal code and state elements.
0,1 .creStateLabel TD containing the state label.
0,1 .creStateField State drop down field.
0,1 .creZipField ZIP/postal code field.
0,1 .creAmountRow TR containing the amount elements.
0,1 .creAmountLabel TD containing the amount label.
0,1 .creAmountField Input containing the amount field.
0,1 .creNumberRow TR containing the credit card number field.
0,1 .creNumberLabel TD containing the credit card label.
0,1 .creNumberField Input containing the credit card number.
0,1 .creCVV2Row TR containing the CVV2 elements.
Page 110 of 121


Type(s)
0,1 .creCVV2Label TD containing CVV2 label.
0,1 .creCVV2Field Input containing the CVV2 input.
0,1 .creCVV2WhatLink Link executing the “What is CVV2” command.
0,1 .creTypeRow TR containing the accepted credit card types.
0,1 .creTypeLabel TD containing the credit card type label.
0,1 .creTypeInput Credit card types drop down.
0,1 .creExpirationRow TR containing the expiration elements.
0,1 .creExpirationLabel TD containing the expiration label.
0,1 .creExpirationMonth Drop down containing the credit card expiration month.
0,1 .creExpirationYear Drop down containing the credit card expiration year.
0,1 .creCardOnFileCheckRow TR containing the “card on file” elements.
0,1 .creCardOnFileCheckLabel TD containing the “card on file” label.
0,1 .creCardOnFileCheck Checkbox input for “card on file.”
0,1 .creButtonRow TR containing the control buttons.
0,1 .creButtonLabel TD holding the control buttons.
0,1,5 .completeButton Button that executes the doComplete method.
0,1 .cancelButton Button that executes the doCancel method.
0,1 .processingComplete OnClick style for the complete button.

Button
0,1 .finishedCompleteButton Persistent style for the complete button after the
transaction is complete.
5 #nameBlock LI containing the customer name elements.
5 #name Input containing the customer name input.
5 #ccTypeBlock LI containing the accepted card types.
5 #ccType Input containing the credit card type label
5 #ccNumberBlock LI containing the credit card number field
5 #ccNumber Input containing the credit card number
5 #expDateBlock LI containing the expiration elements.
5 #expMonth Input containing the expiration month
Page 111 of 121


Type(s)
5 #expYear Input containing the expiration year
5 #cvcBlock LI containing the CVV2 elements
5 #CVV2 Input containing the CVV2 input
0,1,5 .creAccountNameLabel ECP Only: TD containing the name on account label
0,1,5 .creAccountTypeLabel ECP Only: TD containing the account type label
0,1,5 .creAccountNameField ECP Only: Input containing the name on account value
0,1,5 .creAccountTypeField ECP Only: Drop down containing the account type
value
0,1,5 .creRoutingNumberLabel ECP Only: TD containing the routing number label
0,1,5 .creAccountNumberLabel ECP Only: TD containing the DDA account number

label
0,1,5 .creAccountNumberField ECP Only: Input containing the DDA Account number
label
0,1,5 .creBankNameLabel ECP Only: TD containing the bank name label
0,1,5 .creBankNameField ECP Only: Input containing the bank name
Page 112 of 121

Orbital Gateway Hosted Payment Appendix C: Hosted Payment Admin
Appendix C: Hosted Payment Admin

Hosted Payment interface configuration is done through a merchant-facing web interface known as the
Orbital Virtual Terminal. This administrative page allows the merchant to designate the use of the Hosted
Payment Page or the Hosted Payment Form, as well as configure other setup parameters. Initial
configuration of the Hosted Payment interface is required before transactions may be successfully
processed.
Refer to the Orbital Virtual Terminal User’s Manual located in Developer Center for additional information
on how to log in or navigate within the Virtual Terminal.
Note: The Google Chrome browser provides for the best Virtual Terminal viewing experience.
Users with permission to access the Hosted Payment Admin page will find the Admin dropdown list at the
top of the page:
Select the Hosted Solution dropdown to designate an implementation of a Hosted Payment Page or
Hosted Payment Form for the merchant account:
Page 113 of 121

Hosted Payment Form Admin
HPF URL Configuration
Page 114 of 121

Hosted Payment Page Admin
Configuration Steps Common to Both HPF and HPP
Enter the list of approved domains that are authorized to the merchant account profile in the Authorized
Websites field:
Page 115 of 121

Authorized IP Addresses increases security and reduces the likelihood of fraud. If a merchant is using
an Order Abstraction integration, they can add all their server IP addresses in a comma-separated list in
the Authorized IP Addresses box. This list will be checked when uID init requests are sent to the HPF and
HPP. If an IP requesting a uID init request does not exist in the box, that request will be rejected.
If the box is empty, HPF and HPP will not check IP addresses for the uID init requests.
Select the Forced Order Abstraction checkbox to generate a secure payment interface for the merchant
customers. Order Abstraction is a required feature.
Page 116 of 121

American Express does not send CIT/MIT information by default, however Merchant Services will
automatically enable the feature for new customers. For existing customers, select Enable CIT/MIT for
American Express to enable CIT/MIT functionality for American Express transactions.
Note: CEST is not supported for American Express.
Page 117 of 121

Orbital Gateway Hosted Payment Appendix D: Parent Page Code Samples
Appendix D: Parent Page Code Samples

uID Request and Response Sample
uID init Request (must be a server-to-server request)
var.com/direct/services/request/init/?hostedSecureID=xxxx&hostedSecureAPIToken=xxxx&action=buildF
orm&css_url=xxxx&callback_url=xxxx&sessionId=xxxx&amount=1.00&orderId=hps123456
uID init Response
uID=BF7380E2B7xxxxxxxxxxx
Post Messaging Sample






<script>
function handlePaymentErrors(data){
alert( "postMessage function handlePaymentErrors is called. \nError: " +
Object.values(data) );
}
function completePayment(data){
alert("postMessage function completePayment is called. \n Response:"+
Object.values(data) );
alert(data.uID);
}
function hpfReady(){
console.log("HPF Form finished loading.");
}
function scrollRelay(scrollX, scrollY) {
Page 118 of 121

console.log("Scroll X: "+scrollX+ "\nScroll Y: "+scrollY);

}
function startPayment(){
console.log("Payment processing start.");
}
function cancelPayment(){
alert("postMessage function cancelPayment is called. \n You have canceled
the payment.");
}
// For Credit card and ECP payment

function whatsThis(data) {
if(data == "cvv")
{
alert("The 3 numbers on the back of your card.");
}
if(data == "routing")
{
alert("Routing number can be up to 9 digits.");
}
if(data == "account")
{
alert("Account number can be between 3 and 17 digits.");
}
}
// For Credit Card Payment

function whatCVV2() {
alert("The 3 numbers on the back of your card");
}
</script>

<div id="secureFrameWrapper">
<iframe id="secureFrame" class="secureFrame" style="border:1px dashed
slategrey; background-color:#f4f4f4;" height="270px" width="400px"
src="https://www.chasepaymentechhostedpay-var.com/hpf/1_1/?uID=UID_HERE">
</iframe>
</div>
Page 119 of 121

Callback File Sample

<script>
function completeCREPayment( param ) {
var code = decodeURIComponent(param.code);

var message = param.message;
var uID = param.uID;
function removeElement(element) {
element && element.parentNode && element.parentNode.removeChild(element);
}
removeElement( document.getElementById("secureFrame") );
document.getElementById("secureFrameWrapper").innerHTML = "<p>Your
transaction was successful!</p>"
+ "<p>Code: "+code+"</p>"
+ "<p>Message: "+message+"</p>"
+ "<p>uID: "+uID+"</p>";
}
function cancelCREPayment() {
alert("Payment Cancelled");
}
// For Credit card and ECP payment

function whatsThis(data) {
if(data == "cvv")
{
alert("The 3 numbers on the back of your card.");
}
if(data == "routing")
{
alert("Routing number can be up to 9 digits.");
}
if(data == "account")
{
alert("Account number can be between 3 and 17 digits.");
}
}
// For Credit Card Payment

function whatCVV2() {
alert("The 3 numbers on the back of your card");
}
function creHandleDetailErrors( errorCode, gatewayCode, gatewayMessage ) {
alert( "Detailed Error Handler\nError Code: " + errorCode + ", " +
gatewayCode + ", " + gatewayMessage + "." );
}
</script>
<div id="secureFrameWrapper">
Page 120 of 121

<iframe id="secureFrame" class="secureFrame" style="border:1px dashed

slategrey; background-color:#f4f4f4;" height="270px" width="400px"
src="https://www.chasepaymentechhostedpay-var.com/hpf/1_1/?uID=xxxx">
</iframe>
</div>
Page 121 of 121

OGW Hosted Payment Integration Guide v2.7.0.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OGW Hosted Payment Integration Guide v2.7.0.0

Uploaded by

Copyright:

Available Formats

H OSTED P AYMENT S OLUTION

Orbital Gateway Integration Guide

What’s New in Version 2.7.0.0

• Removed duplicate HPF response on a uID Query table

HPP and HPF Web Addresses.................................................................................................................... 36

Frequently Asked Questions ............................................................................................................................... 102

About This Guide

1. A Request Unique ID (uID) is sent to the Request Payment interface.

3. The Hosted Payment interface inputs the customer information.

4. The customer information is used to process the payment.

5. After the payment is processed, the customer experience is completed.

Hosted Payment Page (HPP)

Hosted Payment Form (HPF)

Supported Browser List

Google Chrome 64.0.3282 and higher

Firefox 68.1.0 and higher

Firefox iOS 19.1

Firefox Android 68.1.1

Safari 11.1.2 and higher

Microsoft Edge 40.15063 and higher

Internet Explorer 11 (final version of IE and nearing end of life)

1. Fill out the HPS Admin Area.

2. Build Parent Page.

3. Link to the PostMessaging Script or download the Callback File.

4. Build the uID Request.

5. Send Request to Order Abstraction URL and Get uID back.

7. Create Customer-Facing Response Handling (Javascript functions).

8. Create Merchant-Facing Response Handling (uID query).

Hosted Payment Form

Essential elements for the Integration of HPF

• An iFrame to display the payment form

Technical Prerequisites to HPF Integration

• Website must be accessible via the internet

• Website must use HTML to generate distinct web pages

How Hosted Payment Form Works

Hosted Payment Form Flow Diagram

4. If the information is properly formatted, processing continues. If the processing is unsuccessful:

a. An error is displayed on the page.

5. When the transaction is completed:

See parent page code samples in Appendix D.

There are two methods of response handling:

PostMessage Request and Response

PostMessage Response Handling

The alias function names for postMessaging are handlePaymentErrors(), completePayment(),

Callback Page – File Requirements

 Integrations with modified callback files are not supported.

 Customization of the callback page is not supported.

• Callback URL=URL of the callback page

• CSS URL=URL of style sheet for the HPF

Payment Field Customization

Sample HPF – formType 0 – Short

Sample HPF – formType 1 – Tall

Sample HPF – formType 4 –Mobile phone friendly

Sample HPF – formType 7 – DIV based

Sample HPF – formType 9 – ECP Tableless

Sample HPF – Confirm Routing and Account Numbers

Sample HPF – collectAddress 0 – No Address:

Sample HPF – collectAddress 1 – Domestic Address:

Sample HPF – collectAddress 2 – International Address:

Sample HPF – collectAddress 3 – Zip Code Only

Cascading Style Sheets (CSS)

Hosted Payment Page

Essential Elements for the Integration of HPP