Hosted Payments Page

Configuration Options

Required Parameters

Payment Type Options

UI Customization

Transaction Settings

Profile Management

Advanced Options

Configuration Examples

Minimal Configuration (Credit Card Only)

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

Full-Featured Configuration

var paymentWidget = new hpp({
    // Required
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: "your-bearer-token",
    MerchantId: "merchant-123",

    // Payment types
    ShowPaymentTypeCc: true,
    ShowPaymentTypeAch: true,
    ShowPaymentTypeSwipe: false,
    InitialPaymentType: "CC",
    AllowPaymentTypeToggle: true,

    // UI customization
    ShowAddress: true,
    ShowPhone: true,
    ShowCancel: true,
    HideSubmit: false,
    SubmitButtonText: "Complete Payment",
    CancelButtonText: "Go Back",
    Style: getCustomCSS(),
    Height: "100%",
    Width: "100%",

    // Transaction settings
    AllowPartial: true,
    AllowDuplicateTransaction: false,
    EnforceSurchargeCompliance: true,
    OrderId: "ORDER-2026-001",
    LocationId: 42,
    TransactionEntrySource: 1,
    CorrelationID: generateCorrelationId(),
    LimitedBitFlag: false,

    // Profile management
    PayorId: "",
    RemoveSave: false,
    SaveOnly: false,

    // Advanced options
    FieldVisibility: {
        "Request_Email": true,
        "Request_Phone": true,
        "Request_Address": true
    },
    PresetValues: {
        "Request_Email": "customer@example.com"
    },

    // Event handlers
    OnLoaded: handleLoaded,
    OnSuccess: handleSuccess,
    OnDecline: handleDecline,
    OnError: handleError,
    OnCancel: handleCancel,
    OnChangePaymentType: handlePaymentTypeChange,
    OnBinLookupResponse: handleBinLookup,
    OnAmountChanged: handleAmountChange
});

Save Payment Method Only

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",
    SaveOnly: true,              // Only save, don't charge
    RemoveSave: true,            // Hide save checkbox (always saves)
    SubmitButtonText: "Save Payment Method",
    ShowAddress: true,
    OnSuccess: function(response) {
        console.log("Payment method saved:", response.PayorId);
    }
});

Pre-populated Form

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

    // Pre-fill customer data
    PresetValues: {
        "Request_Name": "Jane Smith",
        "Request_Email": "jane@example.com",
        "Request_Address": "123 Main St",
        "Request_City": "Springfield",
        "Request_Region": "IL",
        "Request_Postal": "62701",
        "Request_Phone": "2175551234"
    },

    OnLoaded: function() {
        console.log("Form loaded with preset values");
    }
});

Custom Styling

// Define custom CSS
var customCSS = `
    body {
        font-family: 'Arial', sans-serif;
        background-color: #f8f9fa;
    }

    .payment-form {
        max-width: 500px;
        margin: 0 auto;
        padding: 20px;
    }

    .field label {
        color: #333;
        font-weight: 600;
    }

    .field input,
    .field select {
        border: 1px solid #ddd;
        border-radius: 4px;
        padding: 10px;
    }

    .btn-primary {
        background-color: #007bff;
        border-color: #007bff;
        padding: 12px 24px;
        font-size: 16px;
    }

    .btn-primary:hover {
        background-color: #0056b3;
    }
`;

var paymentWidget = new hpp({
    Target: "payment-container",
    HPPUrl: "https://your-payment-domain.com/",
    Token: "your-bearer-token",
    MerchantId: "merchant-123",
    ShowPaymentTypeCc: true,
    InitialPaymentType: "CC",
    Style: encodeURIComponent(customCSS)  // Encode CSS for URL
});

Dynamic Field Visibility

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,

    // Initially hide phone, show after loading
    FieldVisibility: {
        "Request_Phone": false
    },

    OnLoaded: function() {
        // Show phone field after a delay
        setTimeout(function() {
            paymentWidget.ToggleFields({
                "Request_Phone": true
            });
        }, 1000);
    },

    OnChangePaymentType: function(paymentType) {
        // Show/hide fields based on payment type
        if (paymentType === "ACH") {
            paymentWidget.ToggleFields({
                "Request_Phone": true,
                "Request_Address": true
            });
        } else {
            paymentWidget.ToggleFields({
                "Request_Phone": false,
                "Request_Address": false
            });
        }
    }
});