Getting Started

There are few basic requirements to get started:

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

2. HTML or Plaintext editor. Form elements will need to be added to existing or new HTML, with either a HTML or Plaintext editor.

3. Merchant Account. A merchant account is required to begin processing live transactions.

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

1. A customer is on a merchant’s e-Commerce website and clicks Checkout.

2. The customer is redirected to the MerchantE Hosted Payment Page

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

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.

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.

<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="submit" value="Checkout">
</form>

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.

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.

tran_date=Fri Mar 27 17:42:42 UTC 2020&acct_number=411111XXXXXX1111&tran_amount=500.00& tran_type=Sale&billing_address=123&tran_id=e0266d9ceaf234dd99427aebe1a13393&currency_code =USD&auth_code=T9939 H&resp_text=ApprovalT9939H&client_ref_number=&retrieval_ref_number= &hpp_tran_id=1971 &billing_zip=12345&resp_code=000&exp_date=1122&invoice_number=

Post Response for a Sales Transaction using ACH

The following response message is for an ACH sales transaction.

auth_type=WEB&amount=500.00&account_type=S&tran_id=1991&ip_address=127.0.0.1&ach_request= SALE&transaction_type=H&ref_num=&resp_text=ACH+IP+Address+Invalid&account_num=XXXXXX4738& profile_key=EtLwsVwzcecgpHqkrNjhXPVyvUnEYHdn&profile_id=94100006000500000001&transit_num= XXXXX0399&resp_code=811&cust_name=name

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.

<?php$ tran_key = md5("EslVInonBTrSMXZzQapRPPQQwVvjAGgi"."test123"."0.03")?>
<input type="text" name="transaction_key" value="<?php echo($tran_key); ?>">

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

function getHttpCredentials() {
$headers = apache_request_headers();
foreach ($headers as $header => $value) {
if(strtolower(substr($value, 0, 5)) == 'basic') {
return base64_decode(substr($value, 6));
    }
  }
}