Getting Started

There are few basic requirements to get started:

Web Hosting. The merchant must have a website which is hosted and publicly available. The Cascading Style Sheet and company logo are hosted by the merchant.
HTML or plain text editor. Form elements will need to be added to existing or new HTML, with either a HTML or plan text editor.
Merchant Account. A merchant account is required to begin processing live transactions.
Submit Final Amount Only. ME Hosted Checkout will only process the amount sent in the transaction_amount field. Shipping charges, local tax, etc. will need to be accommodated before the transaction is submitted.

Transaction Flow

MerchantE’s Hosted Payments will guide your customers through the checkout process to ensure their experience is as simple as possible. When your customer is redirected to your payment page, your customer will have the option to checkout as a guest, create a payment account, or they can log in to make a payment. The checkout experience between guest checkout and a payment account holder checkout is slightly different. Customers that “Checkout as Guest” have a limited view of Hosted Payments.

In both cases, the user will the follow the transaction flow:

A customer is on a merchant’s e-Commerce website and clicks Checkout.
The customer is redirected to the MerchantE Hosted Payment Page
The customer enters their payment details and submits the payment.
1. If the payment is approved, the customer is presented with a payment receipt and has the option to return to the merchant’s website.
2. If the payment is declined, the customer is presented with a generic payment decline and advised to reach out to the issuer for more details.

Integration with Website

The following are the recommended steps to integrate ME’s Hosted Payments into an e-Commerce website.

Obtain a profile ID once the merchant account setup has been completed.

Modify or create HTML pages with ‘buy now’ or ‘checkout’ links or images.

Insert Payment Page URL form (shown below) in HTML.

If necessary, test the form by processing a sale. Ensure that both response URLs function properly.

Payment Page Request Message

You will use the form below to route customers to Hosted Payments. The form will ultimately consist of one or more these request fields:

Field Name	Description	Length	Required	Format
profile_id	Merchant Identifier	20	Y	N
payment_amount	The Amount of the transaction	12	N	N
invoice_number	Custom Invoice Number Field	17	N	A
client_reference_number	Custom Reference Number	96	N	A

Profile ID

This element is mandatory as it is Merchant Identifier routing the customer specifically to your payment page.

Payment Amount

This element is only necessary if you have the Custom Amount flag turned off, since in that scenario the payment amount will be sent across from your website to Hosted Payments.

Note: If you do not send the amount when this flag is turned off, a hardcoded $0.00 amount will be sent when the customer navigates to the Hosted Payment Page and the customer will not be able to proceed with payment.

Invoice Number

This element is only necessary if you intend on sending an Invoice Number to Hosted Payments. If not, this will automatically be generated once the transaction is processed successfully.

Client Reference Number

This element is only necessary if you intend on sending a client reference number from your side to Hosted Payments. If not, this will automatically be generated once the transaction is processed successfully.

Payment Page Request Message Examples

Refer to the following examples to learn how to format request messages in different scenarios.

All Optional information sent

In this example where all optional information is sent, the Custom Amount is off. The Invoice and Ref Number fields are sent as part of the request.

<form action="https://merchante-solutions.com/hpp/checkout/sign-in" method="post">
  <input type=”hidden” name="payment_amount" value="TODO - fill in the Payment Amount"/>
  <input type=”hidden” name="profile_id" value="TODO - fill in the Merchants Profile Id"/>
  <input type=”hidden” name="invoice_number" value="TODO - fill in the Invoice Number"/>
  <input type=”hidden” name="client_reference_number" value="TODO - fill in the Client Ref#"/>
   <input type="submit" value="Checkout">
</form>

No Optional Information Sent

In this example where no Optional Information is sent, the Custom Amount is on. The Invoice and Ref Number fields are not sent as part of the request.

<form action="https://merchante-solutions.com/hpp/checkout/sign-in" method="post">
  <input type=”hidden” name="profile_id" value="TODO - fill in the Merchants Profile Id"/>
   <input type="submit" value="Checkout">
</form>

Custom Amount turned on

In this example, the Custom Amount is turned on. The Invoice and Ref Number fields are sent as part of the request.

<form action="https://merchante-solutions.com/hpp/checkout/sign-in" method="post">
  <input type=”hidden” name="profile_id" value="TODO - fill in the Merchants Profile Id"/>
  <input type=”hidden” name="invoice_number" value="TODO - fill in the Invoice Number"/>
  <input type=”hidden” name="client_reference_number" value="TODO - fill in the Client Ref#"/>
   <input type="submit" value="Checkout">
</form>

Custom Amount turned off

In this example, the Customer Amount is turned off. The Invoice and Ref Number fields are not sent as part of the request.

Post Response Message

The following table contains each field available in the response. It is not necessary to use response data, though it can be helpful to store transaction data, or for integration efforts.

These fields are sent in an HTTP POST to the merchant’s response url once a transaction has been approved. You can set your Response URL in the Advanced URL Management sections of the Settings and Configuration Page in the Hosted Payments Admin section.

Fields	Description
tran_type	The transaction type from the original request.
tran_amount	The amount of the transaction.
invoice_number	Identical to the request field of the same name.
currency_code	Defaults to 840 – USD.
client_ref_number	Identical to the request field of the same name.
acct_number	Truncated card or bank account number.
exp_date	Cardholder expiration date. Format: MMYY
billing_address	Street address entered by the cardholder during checkout.
billing_zip	ZIP Code entered by the cardholder during checkout.
retrieval_ref_number	12-digit MerchantE generated reference number.
auth_code	Authorization code provided by the issuing bank.
resp_code	At this time, resp_code will always be 000 indicating an approved sale.
resp_text	A textual response for the transaction result.
tran_id
tran_date	Timestamp of the transaction. Format: MM/DD/YYYY HH:MM:SS AM/PM
card_id	The returned value is the token for the card which was stored.

Response Example

Refer to the following examples to view the format of response messages that you will receive after sending a request.

Post Response for a Sales Transaction using a Credit Card

The following example response message is for a credit card sales transaction.

Post Response for a Sales Transaction using ACH

The following response message is for an ACH sales transaction.

Security Settings

These settings are intended for advanced integrations of ME Hosted Checkout, and will require a server-side programming language to implement properly, such as PHP, JSP, ASP, etc.

Security Code

The Security Code is a password used to secure requests to ME Hosted Checkout. When a Security Code is set, requests that do not validate will be redirected to the cancel_url appended with the name-pair value resp_text=invalid_tran_key.

To validate a request, create an MD5 hash of the following fields (in this order) :

Profile Key (A security code generated by MerchantE)

Security Code

Transaction Amount

The result of this MD5 hash then needs to be sent in the field transaction_key.

PHP Example of MD5 Hash

The following example shows how the MD5 hash can be formatted in PHP.

There are also two fields:

Resp HTTP Username

Password

These fields are used when sending the response data to the response_url. If present, standard HTTP authentication will be used.

Reading this data will depend on the programming language used, however the first row of the header will be the word BASIC followed by the username and password, Base64 encoded, separated by a colon.

Example 1: Header row 1: BASIC dGVzdDp0ZXN0

Example 2:. dGVzdDp0ZXN0 Base64 decoded: test:test

PHP Example for retrieving Apache headers

The following PHP function will return the decoded authentication pair (test:test in the above example).

MerchantE Knowledge Base

Host Payments Page Implementation