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 you 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:

  • General

    • General Sale - sale
  • Credit Card

    • Sale - ccsale
    • Authorization Only - ccauthonly
    • Verification - ccverify
    • Add Recurring - ccaddrecurring
    • Add Installment - ccaddinstall
    • Get Token - ccgettoken
  • Electronic Check

    • Sale - ecspurchase
    • Add Recurring - ecsaddrecurring
    • Add Installment - ecsaddinstall
  • Gift Card

    • Sale - egcsale

Integration

To integrate with the Converge payment gateway through HPP, 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 the Payment Processing program.

Contact Software Technical Support Team/Customer Service

To implement HPP integration, you will need to contact the Software Technical Support Team or Customer Service by calling 1-800-377-3962 | Option 2 | Option 2, or by emailing #sedevportalsupport@elavon.com. They can help you with the following:

  • Activate the HPP feature and add the necessary information to authenticate your transaction request when passed to Converge.
  • Add the IP address of the server making the session token request to an “allowed” list.
  • Designate a Converge user ID with a Hosted Payment API User status in order to post a session token request.

Customize your Hosted Payment Page checkout form

For more details on the configuration of the HPP checkout form, refer to the customize hosted paymentsLink opens new window.

Develop the Payment Processing program

The Payment Processing program that you will develop must include session token request function, redirect to hosted payment form function and call back response handling function.

Session Token Request

Your session token request function must include the following parameters:

Field nameDescriptionRequiredLengthData type
ssl_merchant_idMerchant ID
Elavon-assigned Converge Account ID (AID).
Required6 or 7numeric
ssl_user_idConverge User ID
The user ID with hosted payment API user status that can send transaction requests through the terminal.
Required15alphanumeric
ssl_pinTerminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
Important: The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.
Required64alphanumeric
ssl_transaction_typeTransaction TypeRequired20alphanumeric
ssl_amountTransaction Amount
Data entry depends on the ssl_transaction_type value.
Conditional11numeric

The endpoints to POST the session token request 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 HPP by posting the session token obtained previously.

Your redirect to hosted payment form function must include this parameter:

Field nameDescriptionRequiredLengthData type
ssl_txn_auth_tokenSession Token ResponseRequired50alphanumeric

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 HPP configuration, Converge can post the transaction response to your website. You can use the response to update your backend system and display the appropriate response to the customer.

HTML Sample Code

<html>
<head>
</head>
<body>
    <h3>HPP Demo</h3>
    <form action="request_session_token_demo.php" name="test1" method="post">
        <table border="1" bordercolorlight="#C0C0C0" cellspacing="5" bordercolordark="#FFFFFF">
            <tr>
                <td>Trans Amount</td>
                <td><input type="text" name="ssl_amount" size="6" value="1.00"></td>
            </tr>
            <tr>
                <td>Transaction Type</td>
                <td>
                    <select size="1" name="ssl_transaction_type">
                        <option value="CCSALE">Credit Card Sale</option>
                        <option value="CCAUTHONLY">Credit Card Authorization Only</option>
                        <option value="CCVerify">Credit Card Verification </option>
                        <option value="CCGETTOKEN">Credit Card Get Token</option>
                        <option value="SALE">Generic Sale</option>
                        <option value="AUTHONLY">Generic Authorization Only</option>
                        <option value="ecspurchase">ACH</option>
                        <option value="EGCSALE">Gift Card</option>
                    </select>
                </td>
            </tr>
            <tr>
                <td colspan="2">&nbsp;</td>
            </tr>
            <tr>
                <td colspan="2">
                    <p align="center">Redirect to NG HPP</p>
                </td>
            </tr>
            <tr>
                <td colspan="2" align="center">
                    <input type="submit" value="Pay Now" name="Submit">
                </td>
            </tr>
        </table>
    </form>
</body>
</html>

PHP Sample Code for HPP

This is an example PHP call to process a payment through Converge’s HPP.

Information as requested can be provided 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

  if ($result === false) {
       echo 'Curl error message: '.curl_error($ch).'<br>';
       echo 'Curl error code: '.curl_errno($ch);
  } else {
     $httpstatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($httpstatus == 200) {            
        $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
   } else {
        echo 'Response: '.$result.'<br>';
        echo 'HTTP status: '.$httpstatus;
        }
    }

    curl_close($ch); // Close cURL

 

    exit;



   ?>