Hosted Payment Pages

Collect payment information securely without handling card data directly. PayConnect's hosted payment pages are PCI-compliant forms that tokenize sensitive payment data on your behalf.

Overview

Hosted payment pages allow you to:

• Accept credit card and ACH payments without PCI scope on your servers
• Tokenize card data into reusable account vaults for future charges
• Embed payment forms directly in your application or redirect to a hosted page
• Customize accepted payment methods per transaction

How It Works

1. Your Server  →  Create payment intention  →  PayConnect API
2. PayConnect   →  Return client token       →  Your Server
3. Your Server  →  Render payment form        →  Customer Browser
4. Customer     →  Enter payment details      →  Hosted Form (PCI-secure)
5. Hosted Form  →  Tokenize & process         →  PayConnect
6. PayConnect   →  Webhook notification       →  Your Server

Payment Intention

A payment intention generates a secure client token for rendering the hosted payment form.

Create a Payment Intention

cURL

curl -X POST https://dev.payconnect.us/api/payment/intention \
  -H "x-session-token: YOUR_SESSION_TOKEN" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "paymentMethods": ["cc", "ach"]
  }'

Node.js

const axios = require("axios");

const response = await axios.post(
  "https://dev.payconnect.us/api/payment/intention",
  {
    customerId: "cust_abc123",
    paymentMethods: ["cc", "ach"],
  },
  {
    headers: {
      "x-session-token": "YOUR_SESSION_TOKEN",
      "x-correlation-id": "YOUR_CORRELATION_ID",
      "Content-Type": "application/json",
    },
  }
);

const { clientToken, locationId, methods } = response.data;

Python

import requests

response = requests.post(
    "https://dev.payconnect.us/api/payment/intention",
    headers={
        "x-session-token": "YOUR_SESSION_TOKEN",
        "x-correlation-id": "YOUR_CORRELATION_ID",
        "Content-Type": "application/json",
    },
    json={
        "customerId": "cust_abc123",
        "paymentMethods": ["cc", "ach"],
    },
)

data = response.json()
client_token = data["clientToken"]

Response:

{
  "clientToken": "eyJhbGciOiJIUzI1NiIs...",
  "locationId": "loc_abc123",
  "contactId": "cnt_abc123",
  "methods": [
    {
      "productTransactionId": "ptx_cc_123",
      "type": "cc"
    },
    {
      "productTransactionId": "ptx_ach_456",
      "type": "ach"
    }
  ]
}

Request Fields

Field	Type	Required	Description
customerId	string	No	PayConnect customer id to link the payment to (a processor contact is resolved or created for them). Omit for an anonymous payment.
paymentMethods	array	No	Accepted methods: ["cc"], ["ach"], or ["cc", "ach"] (default: both)

Hosted Payment Page (Redirect)

For a simpler integration, generate a full-page hosted payment URL. This is a public endpoint — no authentication header is required:

curl -X POST https://dev.payconnect.us/api/trx/hostedpayment \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "hpp_token": "YOUR_HPP_TOKEN",
    "total": 50,
    "order_id": "ORD-2026-001",
    "title": "Payment for Order #001",
    "email": "[email protected]",
    "description": "Monthly service fee"
  }'

Response:

{
  "token": "hpp_token_abc123",
  "url": "https://my.payconnect.us/pay/hpp_token_abc123"
}

Redirect your customer to the url to complete payment. After payment, PayConnect sends a postback to your configured postback URL.

Request Fields

Field	Type	Required	Description
hpp_token	string	Yes	Company hosted-payment-page token that identifies and authenticates the merchant. Required for the direct payform flow.
total	number	Yes	Amount in dollars (e.g. 50 = $50.00). Required for the direct payform flow.
order_id	string	No	Your order reference ID
title	string	No	Page title
firstName	string	No	Ignored by this pay-form endpoint (only used by the account-form variant)
lastName	string	No	Ignored by this pay-form endpoint (only used by the account-form variant)
email	string	No	Customer email
description	string	No	Payment description
billing_street	string	No	Pre-fill billing address
billing_city	string	No	Pre-fill billing city
billing_state	string	No	Pre-fill billing state
billing_zip	string	No	Pre-fill billing ZIP
line_items	array	No	Line item details
image_url	string	No	Custom logo URL for the payment page

Invoice Payment Pages

Invoices automatically include hosted payment pages. When you create an invoice with sendEmail: true, the customer receives an email with a link to pay.

The invoice payment page:

• Displays invoice details, line items, and amount due
• Shows your company name and branding
• Accepts the payment methods configured on the invoice
• Supports partial payments when applicable
• Provides a payment confirmation after completion

See the Invoices guide for creating invoices.

Subscription Payment Pages

Subscriptions use hosted payment pages for initial payment method collection and updates. The subscription payment page:

• Displays the subscription plan details and amount
• Collects and tokenizes the customer's payment method
• Supports both credit card and ACH

See the Subscriptions guide for details.

Security

All hosted payment pages are:

• PCI DSS compliant — card data is processed in a PCI-certified environment
• HTTPS only — all pages are served over TLS
• Tokenized — sensitive card data is never exposed to your servers
• Time-limited — payment tokens expire to prevent unauthorized use

tip

Using hosted payment pages keeps your application out of PCI scope. You never handle raw card numbers, CVVs, or bank account details directly.

Next Steps

• Invoices — send invoices with built-in payment pages
• Customers — manage stored payment methods
• Transactions — charge stored payment methods
• Postbacks — receive payment notifications
• API Reference — full endpoint documentation