Integration - Hosted Payments Page Documentation

Integration Guide

1. Include the HPP JavaScript Library

Add the HPP library to your HTML page:

<script src="https://your-payment-domain.com/scripts/hpp.js"></script>

2. Create a Container Element

Add a div element where the payment form will be embedded:

<div id="payment-container"></div>

3. Initialize the Payment Widget

Create an instance of the HPP with your configuration:

var paymentWidget = new hpp({
    // Required parameters
    Target: "payment-container",           // ID of the container element
    HPPUrl: "https://your-payment-domain.com/",
    Token: "your-bearer-token",            // Authentication token
    MerchantId: "your-merchant-id",

    // Payment type options (at least one must be true)
    ShowPaymentTypeCc: true,               // Enable credit card payments
    ShowPaymentTypeAch: true,              // Enable ACH payments
    ShowPaymentTypeSwipe: false,           // Enable card swipe
    InitialPaymentType: "CC",              // "CC", "ACH", or "SWIPE"

    // Optional UI customization
    ShowAddress: true,                     // Show address fields
    ShowPhone: true,                       // Show phone field
    ShowCancel: true,                      // Show cancel button
    HideSubmit: false,                     // Hide submit button
    AllowPaymentTypeToggle: true,          // Allow switching payment types

    // Optional button text
    SubmitButtonText: "Pay Now",
    CancelButtonText: "Cancel",

    // Optional styling
    Style: "custom-css-url-or-inline",
    Height: "100%",
    Width: "100%",

    // Optional transaction settings
    AllowPartial: true,                    // Allow partial payments
    AllowDuplicateTransaction: false,      // Prevent duplicate transactions
    EnforceSurchargeCompliance: false,     // Enforce surcharge rules

    // Optional profile management
    PayorId: "",                           // Pre-populate with existing payor
    RemoveSave: false,                     // Remove "save card" option
    SaveOnly: false,                       // Only save, don't charge

    // Optional metadata
    OrderId: "order-12345",
    LocationId: 100,
    TransactionEntrySource: 1,
    CorrelationID: "custom-correlation-id",
    LimitedBitFlag: false,

    // Event callbacks (see Events section)
    OnLoaded: function(event) {
        console.log("Payment form loaded", event);
    },
    OnSuccess: function(response) {
        console.log("Payment successful", response);
    },
    OnDecline: function(response) {
        console.log("Payment declined", response);
    },
    OnError: function(error) {
        console.error("Payment error", error);
    },
    OnCancel: function(detail) {
        console.log("Payment cancelled", detail);
    }
});

4. Initialize with Amount and Surcharge

// Initialize the payment form with amount and optional surcharge
paymentWidget.Initialize(100.00, 2.50);  // $100.00 + $2.50 surcharge

5. Handle Payment Response

The payment response will be delivered via the callback functions you configured. The widget will automatically display success or error messages within the iframe.

Complete Example:

<!DOCTYPE html>
<html>
<head>
    <title>Payment Example</title>
    <script src="https://your-payment-domain.com/scripts/hpp.js"></script>
</head>
<body>
    <div id="payment-container"></div>

    <script>
        var paymentWidget = new hpp({
            Target: "payment-container",
            HPPUrl: "https://your-payment-domain.com/",
            Token: "your-bearer-token",
            MerchantId: "merchant-123",
            ShowPaymentTypeCc: true,
            ShowPaymentTypeAch: true,
            InitialPaymentType: "CC",
            OnSuccess: function(response) {
                alert("Payment successful! Transaction ID: " + response.TransactionId);
            },
            OnDecline: function(response) {
                alert("Payment declined: " + response.ResponseMessage);
            }
        });

        // Initialize with $50.00 amount, no surcharge
        paymentWidget.Initialize(50.00, 0);
    </script>
</body>
</html>

Advanced Integration Scenarios

E-commerce Checkout Integration

<!-- Checkout page -->
<div class="checkout-container">
    <div class="order-summary">
        <h3>Order Summary</h3>
        <p>Subtotal: <span id="subtotal">$97.50</span></p>
        <p>Surcharge: <span id="surcharge">$2.50</span></p>
        <p>Total: <span id="total">$100.00</span></p>
    </div>

    <div id="payment-container"></div>
</div>

<script>
var cart = getCartData();
var subtotal = cart.calculateSubtotal();
var surcharge = cart.calculateSurcharge();

var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    ShowPaymentTypeAch: true,
    InitialPaymentType: "CC",
    ShowAddress: true,
    ShowPhone: true,
    OrderId: cart.orderId,

    OnLoaded: function(event) {
        // Pre-fill customer information
        var customer = getCustomerInfo();
        if (customer) {
            paymentWidget.SetFormValues({
                "Request_Name": customer.name,
                "Request_Email": customer.email,
                "Request_Address": customer.address,
                "Request_City": customer.city,
                "Request_Region": customer.state,
                "Request_Postal": customer.zip
            });
        }
    },

    OnAmountChanged: function(detail) {
        // Update display when surcharge changes
        document.getElementById('surcharge').textContent =
            '$' + (detail.newAmount - subtotal).toFixed(2);
        document.getElementById('total').textContent =
            '$' + detail.newAmount.toFixed(2);
    },

    OnSuccess: function(response) {
        // Store transaction details
        saveTransactionDetails(cart.orderId, response);
        // Redirect to confirmation page
        window.location.href = '/order-confirmation?id=' + cart.orderId;
    },

    OnDecline: function(response) {
        showError("Payment declined: " + response.ResponseMessage);
    },

    OnError: function(error) {
        showError("An error occurred. Please try again.");
        logError(error);
    }
});

paymentWidget.Initialize(subtotal + surcharge, surcharge);
</script>

Save Payment Method Only

<!-- Account management page -->
<div id="payment-method-container"></div>

<script>
var paymentWidget = new hpp({
    Target: "payment-method-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    ShowPaymentTypeAch: true,
    InitialPaymentType: "CC",
    SaveOnly: true,  // Don't process payment, only save method
    RemoveSave: true,  // Hide "save card" checkbox (always saves)
    ShowAddress: true,
    ShowPhone: true,
    SubmitButtonText: "Add Payment Method",

    OnSuccess: function(response) {
        alert("Payment method saved successfully!");
        // Refresh payment methods list
        loadPaymentMethods();
    },

    OnError: function(error) {
        alert("Failed to save payment method: " + error);
    }
});

// Amount is required but ignored for SaveOnly mode
paymentWidget.Initialize(0, 0);
</script>

Dynamic Amount Updates

<div>
    <label>Payment Amount: $</label>
    <input type="number" id="amount-input" value="50.00" step="0.01" min="1">
    <button onclick="updateAmount()">Update</button>
</div>

<div id="payment-container"></div>

<script>
var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",
    OnSuccess: function(response) {
        alert("Payment successful! Amount: $" + response.AuthAmount);
    }
});

paymentWidget.Initialize(50.00, 0);

function updateAmount() {
    var newAmount = parseFloat(document.getElementById('amount-input').value);
    if (newAmount < 1) {
        alert("Amount must be at least $1.00");
        return;
    }

    var surcharge = calculateSurcharge(newAmount);
    paymentWidget.SetAmount(newAmount, surcharge);
}
</script>

Custom Submit Validation

<div id="payment-container"></div>
<div id="terms-container">
    <input type="checkbox" id="terms-checkbox">
    <label for="terms-checkbox">I agree to the terms and conditions</label>
</div>

<script>
var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",

    OnSubmit: function(amount) {
        // Check if terms are accepted
        if (!document.getElementById('terms-checkbox').checked) {
            alert("You must accept the terms and conditions.");
            return; // Don't call SubmitOk() - submission blocked
        }

        // Confirm payment
        if (confirm("Process payment of $" + amount + "?")) {
            paymentWidget.SubmitOk();  // Allow submission
        }
    },

    OnSuccess: function(response) {
        console.log("Payment successful:", response);
    }
});

paymentWidget.Initialize(100.00, 0);
</script>

Multiple Payment Forms on One Page

<div class="payment-section">
    <h3>Pay Invoice #1234</h3>
    <div id="payment-container-1"></div>
</div>

<div class="payment-section">
    <h3>Pay Invoice #5678</h3>
    <div id="payment-container-2"></div>
</div>

<script>
// First payment widget
var paymentWidget1 = new hpp({
    Target: "payment-container-1",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",
    OrderId: "1234",
    OnSuccess: function(response) {
        alert("Invoice #1234 paid successfully!");
    }
});
paymentWidget1.Initialize(150.00, 0);

// Second payment widget
var paymentWidget2 = new hpp({
    Target: "payment-container-2",
    HPPUrl: "https://your-payment-domain.com/",
    Token: getAuthToken(),
    MerchantId: getMerchantId(),
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",
    OrderId: "5678",
    OnSuccess: function(response) {
        alert("Invoice #5678 paid successfully!");
    }
});
paymentWidget2.Initialize(75.00, 0);
</script>

Cleanup and Reinitialization

// When user navigates to a different section
function showDifferentContent() {
    // Clean up the payment widget
    if (paymentWidget) {
        paymentWidget.Clear();
    }

    // Show other content
    document.getElementById('payment-container').style.display = 'none';
    document.getElementById('other-content').style.display = 'block';
}

// To reinitialize later
function showPaymentForm() {
    document.getElementById('payment-container').style.display = 'block';

    paymentWidget = new hpp({
        // ... configuration ...
    });

    paymentWidget.Initialize(amount, surcharge);
}