Hosted Payments Page

API Methods

The HPP widget provides several methods to control the payment form programmatically:

Core Methods

Data Manipulation Methods

UI Control Methods

Method Examples

Initialize the Payment Form

// Create widget instance
var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: "your-bearer-token",
    MerchantId: "merchant-123",
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC"
});

// Load form with $125.00 amount and $3.00 surcharge
paymentWidget.Initialize(125.00, 3.00);

Update Amount Dynamically

// Update to new amount (e.g., after user adds items to cart)
var newSubtotal = calculateCartTotal();
var newSurcharge = calculateSurcharge(newSubtotal);

paymentWidget.SetAmount(newSubtotal + newSurcharge, newSurcharge);

// Example with user input
function updateAmount() {
    var amount = parseFloat(document.getElementById('amount-input').value);
    if (amount >= 1.00) {
        paymentWidget.SetAmount(amount, 0);
    } else {
        alert('Amount must be at least $1.00');
    }
}

Pre-fill Form Fields

// Pre-populate customer information after form loads
OnLoaded: function(event) {
    var customer = getCustomerData();

    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.zipCode,
        "Request_Phone": customer.phone
    });
}

// Set values before form loads using PresetValues option
var paymentWidget = new hpp({
    // ... other config ...
    PresetValues: {
        "Request_Name": "Jane Smith",
        "Request_Email": "jane@example.com"
    }
});

Toggle Field Visibility

// Hide phone field, show address fields
paymentWidget.ToggleFields({
    "Request_Phone": false,
    "Request_Address": true,
    "Request_City": true,
    "Request_Region": true
});

// Toggle based on payment type
OnChangePaymentType: function(paymentType) {
    if (paymentType === "ACH") {
        // Show all address fields for ACH
        paymentWidget.ToggleFields({
            "Request_Address": true,
            "Request_City": true,
            "Request_Region": true,
            "Request_Phone": true
        });
    } else {
        // Hide extra fields for credit card
        paymentWidget.ToggleFields({
            "Request_Address": false,
            "Request_City": false,
            "Request_Region": false,
            "Request_Phone": false
        });
    }
}

// Toggle based on checkbox
document.getElementById('show-address').addEventListener('change', function(e) {
    var showAddress = e.target.checked;
    paymentWidget.ToggleFields({
        "Request_Address": showAddress,
        "Request_City": showAddress,
        "Request_Region": showAddress
    });
});

Get Current Field Values

// Request field values
paymentWidget.GetFieldValues({
    "Request_Name": true,
    "Request_Email": true,
    "Request_Postal": true
});

// Handle the response in callback
OnGetFieldValue: function(values) {
    console.log("Name:", values.Request_Name);
    console.log("Email:", values.Request_Email);
    console.log("Postal:", values.Request_Postal);

    // Use values for validation
    if (values.Request_Email && !isValidEmail(values.Request_Email)) {
        alert("Please enter a valid email address");
    }

    // Use postal code to calculate tax
    if (values.Request_Postal) {
        calculateTaxRate(values.Request_Postal);
    }

    // Store values for later use
    sessionStorage.setItem('customerData', JSON.stringify(values));
}

// Button to retrieve values
document.getElementById('get-info-btn').addEventListener('click', function() {
    paymentWidget.GetFieldValues({
        "Request_Name": true,
        "Request_Email": true,
        "Request_Phone": true
    });
});

Validate Before Submission

var paymentWidget = new hpp({
    // ... other config ...

    OnSubmit: function(amount) {
        // Perform custom validation
        if (amount < 1.00) {
            alert("Amount must be at least $1.00");
            return; // Don't call SubmitOk() - submission is blocked
        }

        // Check if terms are accepted
        if (!document.getElementById('terms-checkbox').checked) {
            alert("Please accept the terms and conditions");
            return; // Submission blocked
        }

        // Get field values for additional validation
        paymentWidget.GetFieldValues({
            "Request_Email": true
        });

        // Note: In a real implementation, you'd validate in OnGetFieldValue
        // For this example, we'll just confirm
        if (confirm("Process payment of $" + amount + "?")) {
            paymentWidget.SubmitOk();  // Allow submission to proceed
        }
        // If SubmitOk() is not called, the form won't submit
    }
});

Manual Resize Trigger

// Manually trigger resize after making UI changes
function expandSection() {
    document.getElementById('additional-info').style.display = 'block';

    // Give the content time to render, then resize
    setTimeout(function() {
        paymentWidget.Resize();
    }, 100);
}

// Resize after window resize
window.addEventListener('resize', function() {
    if (paymentWidget) {
        paymentWidget.Resize();
    }
});

Clean Up Widget

// Remove iframe and clean up event listeners
function closePaymentForm() {
    if (paymentWidget) {
        paymentWidget.Clear();
        paymentWidget = null;
    }

    // Hide container
    document.getElementById('payment-container').style.display = 'none';
}

// Clean up on page unload
window.addEventListener('beforeunload', function() {
    if (paymentWidget) {
        paymentWidget.Clear();
    }
});

// Clean up when navigating away
function navigateAway() {
    closePaymentForm();
    window.location.href = '/other-page';
}

Advanced Method Usage

Dynamic Form Configuration

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",
    AllowPaymentTypeToggle: true,

    OnLoaded: function() {
        // Get user preferences
        var preferences = getUserPreferences();

        // Configure fields based on preferences
        if (preferences.hidePhone) {
            paymentWidget.ToggleFields({"Request_Phone": false});
        }

        // Pre-fill saved information
        if (preferences.savedInfo) {
            paymentWidget.SetFormValues(preferences.savedInfo);
        }

        // Set initial amount from cart
        var cartTotal = getCartTotal();
        paymentWidget.SetAmount(cartTotal, 0);
    },

    OnChangePaymentType: function(paymentType) {
        // Adjust visible fields based on payment type
        var fieldsConfig = getFieldsForPaymentType(paymentType);
        paymentWidget.ToggleFields(fieldsConfig);

        // Update amount if surcharge rules change
        var newAmount = recalculateAmount(paymentType);
        paymentWidget.SetAmount(newAmount.total, newAmount.surcharge);
    }
});

paymentWidget.Initialize(0, 0);  // Will be set in OnLoaded

Chaining Method Calls

// Initialize and immediately configure
var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: "your-bearer-token",
    MerchantId: "merchant-123",
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",

    OnLoaded: function() {
        // Chain multiple configuration calls
        paymentWidget.SetFormValues({
            "Request_Name": "John Doe",
            "Request_Email": "john@example.com"
        });

        paymentWidget.ToggleFields({
            "Request_Phone": true,
            "Request_Address": true
        });

        paymentWidget.SetAmount(100.00, 2.50);
        paymentWidget.Resize();
    }
});

paymentWidget.Initialize(50.00, 0);

Field ID Reference