Hosted Payments

Hosted Payments integration enables your eCommerce store to collect payments securely and is ideal for businesses that need a checkout page that:

• Links their custom-built website with the Converge payment gateway
• Allows Converge to handle card data and payment processing
• Is simple to implement and customer friendly
• Is Americans with Disabilities Act (ADA) compliant

Hosted Payments Page (HPP) integration offers checkout/payment forms that are SAQ-A-compliant and that make collecting payment information from your customer easy, and without the payment data touching your server.

HPP provides a template that helps your create a modern, customized, and responsive checkout page. HPP also enables you to brand your checkout page with your business logo and color schemes.

Payment and Transaction Types

HPP integration supports the following transaction types of each payment type:

Integration

To integrate with the Converge payment gateway through Hosted Payments Page, your will need to complete the following:

1. Contact Software Technical Support Team or Customer Service .
2. Customize your Hosted Payment Page checkout form .
3. Develop a Payment Processing program .

Contact Software Technical Support Team/Customer Service

To implement Hosted Payments integration, you will need to contact the Software Technical Support Team or Customer Service at 1-800-377-3962 | Option 2 | Option 2 to:

• Activate the HPP feature and whitelist the necessary information to authenticate your transaction request when passed to Converge.
• Whitelist the IP address of the server making the session token request.
• Designate a Converge user ID with a Hosted Payment API User status in order to post a session token request.
• Associate the Converge user ID with the eCommerce terminal.
• Register the website URL from which the request to redirect to the hosted payment form originates.

Customize the checkout form

To customize your HPP checkout form, complete these steps:

1. Log in to your Converge demo site.
2. Click Home. The Client Accounts page appears.
3. Search for the terminal that handles eCommerce transaction processing.
4. Select the terminal by clicking its name under the Terminal Name column. The Settings page appears.
5. Under Advanced API Settings, click Hosted Payments. The Which solution is right for you page appears.

6. Customize your checkout form.

   In customizing the checkout page, you will need to configure the following pages:

   • Payment Page
   • Response Page

   Click the SETUP button for Hosted payment page setup, configure the Payment and Response pages, and click SAVE to complete the customization of your HPP page.

Configure the Payment page

To configure the Payment page, complete these steps:

1. Click the PAYMENT PAGE tab (if needed).
2. Click a Section link and choose the fields you want to display on each section of the checkout page.
   

   Section	Action to Take
   Order Summary	Select the checkboxes of the appropriate payment fields.
   Payment Summary	Select the checkboxes of the applicable payment methods.
   Billing Address	You can toggle the Billing Address button to set the display setting of the fields. If enabled, select the checkboxes of the applicable address fields.
   Shipping Address	You can toggle the Shipping Address button to set the display setting of the fields. If enabled, select the checkboxes of the applicable address fields.

3. Configure the following design settings.
   

   Setting	Action to Take
   Theme	Select the color scheme. If you select Custom, enter the hexadecimal color codes for these elements: Header Background Button Text
   Button Text	Enter the label for the submit transaction button.
   Header Text	Select the font, font size, font style, and alignment. Enter the description that appears on the header section.
   Footer Text	Select the font, font size, font stle, and alignment. Enter the description that appears on the footer section.

4. Configure the payment cancellation settings.
   

   Setting	Action to Take
   Cancel Text	Enter the label for the cancel transaction link.
   Cancel Link	Enter the URL of the redirect page for cancelled payments.
   Include Original Post Data	Select the checkbox to include the data of the original transaction.

5. Select the Enable CAPTCHA checkbox to include a challenge-response test to the payment page.
6. Click PREVIEW PAYMENT PAGE to review your customized checkout page.

Configure the Response page

In customizing the Response page, you will need to configure these pages and setting:

• Approval Page
• Decline Page
• Redirect URL

Click the RESPONSE PAGE tab then configure the Approval page, Decline page, and Redirect URL.

Configure the Approval page

To configure the Approval page, complete these steps:

1. Click the APPROVAL PAGE tab (if needed).
2. Click a Section link and choose the fields you want to display on each seaction of the checkout page.
   

   Section	Action to Take
   Confirmation	Select the checkboxes of the appropriate response data fields.
   Order Summary	Select the checkboxes of the applicable transaction data fields.
   Billing Address	You can toggle the Billing Address button to set the display setting of the fields. If enabled, select the checkboxes of the applicable address fields.
   Shipping Address	You can toggle the Shipping Address button to set the display setting of the fields. If enabled, select the checkboxes of the applicable address fields.

3. Configure the payment completion settings.
   

   Setting	Action to Take
   Button Text	Enter the label for the complete transaction button.
   Button Link	Enter the URL of the redirect page for approved payments.
   Include Original Post Data	Select the checkbox to include the data of the original transaction.

4. Configure the following design settings.
   

   Setting	Action to Take
   Header Text	Select the font, font size, font style, and alignment. Enter the description that appears on the header section.
   Footer Text	Select the font, font size, font stle, and alignment. Enter the description that appears on the footer section.

5. Click PREVIEW RESPONSE PAGE to review your customized approval page.

Configure the Decline page

To configure the Decline page, complete these steps:

1. Click the DECLINE PAGE tab.
2. In the Custom Message field, enter the additional text that will appear with the pre-defined declined payment message.
3. Configure the declined payment settings.
   

   Setting	Action to Take
   Button Text	Enter the label for the decline transaction button.
   Button Link	Enter the URL of the redirect page for declined payments.
   Include Original Post Data	Select the checkbox to include the data of the original transaction.

4. Click PREVIEW RESPONSE PAGE to review your customized decline page.

Configure the Redirect URL

To configure the redirect page settings, complete these steps:

1. Click the REDIRECT URL tab.
2. In the Redirect URL field, enter the URL of your website to which to redirect your customer and the payment confirmation data.

Develop the Payment Processing program

The Payment Processing program that you will develop must include functions for the following:

1. Session Token Request
2. Redirect to Hosted Payment Form
3. Call Back Response Handling

Session Token Request

Your session token request function must include the following parameters:

The endpoints to POST the session token request to are as follows:

• Demo Site: https://api.demo.convergepay.com/hosted-payments/transaction_token
• Live Site: https://api.convergepay.com/hosted-payments/transaction_token

Your session token request function must be able to capture the Session Token Response from Converge.

Note: The Session Token Response is only valid for 15 minutes and can only be used once.

Redirect to Hosted Payment Form

Once the session token is obtained, you should redirect the customer's browser to the Hosted Payments Page by posting the session token obtained previously. The redirection request must come from a website URL that is registered with Converge.

Your Redirect to Hosted Payments Page Form function must include this parameter:

The endpoints to POST the redirect request to are as follows:

• Demo Site: https://api.demo.convergepay.com/hosted-payments/
• Live Site: https://api.convergepay.com/hosted-payments/

Call Back Response Handling

Based on your hosted payments configuration, Converge can post the transaction response to your website. You can use the response to update our backend system and display the appropriate response to the customer.

PHP Sample Code for Hosted Payments Page

This is an example PHP call to process a payment through Converge's hosted payments.

Provide information as requested in the code comments.

By default, the Converge Demo environment is the live url in this code. To use this code in production, remove the demo environment URL and uncomment the production URL.

  <?php

   // Provide Converge Credentials
  $merchantID = "XXXXXX"; //Converge 6-Digit Account ID *Not the 10-Digit Elavon Merchant ID*
  $merchantUserID = "ConvergeAPIHostedUser"; //Converge User ID *MUST FLAG AS HOSTED API USER IN CONVERGE UI*
  $merchantPIN = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; //Converge PIN (64 CHAR A/N)

  $url = "https://api.demo.convergepay.com/hosted-payments/transaction_token"; // URL to Converge demo session token server
  //$url = "https://api.convergepay.com/hosted-payments/transaction_token"; // URL to Converge production session token server

  $hppurl = "https://api.demo.convergepay.com/hosted-payments"; // URL to the demo Hosted Payments Page
  //$hppurl = "https://api.convergepay.com/hosted-payments"; // URL to the production Hosted Payments Page

  /*Payment Field Variables*/

  // In this section, we set variables to be captured by the PHP file and passed to Converge in the curl request.

  $amount= '1.00'; //Hard-coded transaction amount for testing.

  //$amount  = $_POST['ssl_amount'];   //Capture ssl_amount as POST data
  //$firstname  = $_POST['ssl_first_name'];   //Capture ssl_first_name as POST data
  //$lastname  = $_POST['ssl_last_name'];   //Capture ssl_last_name as POST data
  //$merchanttxnid = $_POST['ssl_merchant_txn_id']; //Capture ssl_merchant_txn_id as POST data
  //$invoicenumber = $_POST['ssl_invoice_number']; //Capture ssl_invoice_number as POST data

  //Follow the above pattern to add additional fields to be sent in curl request below.

  $ch = curl_init();    // initialize curl handle
  curl_setopt($ch, CURLOPT_URL,$url); // set POST target URL
  curl_setopt($ch,CURLOPT_POST, true); // set POST method
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  //Build the request for the session id. Make sure all payment field variables created above get included in the CURLOPT_POSTFIELDS section below.

  curl_setopt($ch,CURLOPT_POSTFIELDS,
  "ssl_merchant_id=$merchantID".
  "&ssl_user_id=$merchantUserID".
  "&ssl_pin=$merchantPIN".
  "&ssl_transaction_type=ccsale".
  "&ssl_amount=$amount"
  );

  $result = curl_exec($ch); // run the curl to post to Converge
  curl_close($ch); // Close cURL

  $sessiontoken= urlencode($result);

  /* Now we redirect to the HPP */

  header("Location: https://api.demo.convergepay.com/hosted-payments?ssl_txn_auth_token=$sessiontoken");  //Demo Redirect
  //header("Location: https://api.convergepay.com/hosted-payments?ssl_txn_auth_token=$sessiontoken"); //Prod Redirect

  exit;

   ?>

• previous Checkout.js Methods and Parameters
• next Lightbox