Hosted Payment Page

The hosted payment page is the simplest way to accept payments. Redirect payers to a GovPayPlan-hosted page where they complete their payment.

How It Works

1. Your application creates a payment session
2. Redirect payer to the hosted payment page
3. Payer enters payment information
4. GovPayPlan processes the payment
5. Payer is redirected back to your site
6. Webhook notifies your server of the result

Benefits

• No PCI scope: Payment data never touches your servers
• Quick setup: Minimal development required
• Mobile-friendly: Responsive design included
• Always up-to-date: Security updates handled automatically

Implementation

Step 1: Create a Payment Session

curl -X POST https://api.govpayplan.com/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "payment_type": "permit_fee",
    "description": "Building Permit #12345",
    "reference_id": "PERMIT-12345",
    "success_url": "https://yoursite.com/payment/success",
    "cancel_url": "https://yoursite.com/payment/cancel",
    "payer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

Response

{
  "success": true,
  "data": {
    "session_id": "sess_abc123",
    "payment_url": "https://pay.govpayplan.com/sess_abc123",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}

Step 2: Redirect to Payment Page

Redirect the payer to the payment_url:

<a href="https://pay.govpayplan.com/sess_abc123">
  Pay Now
</a>

Or redirect via JavaScript:

window.location.href = paymentUrl;

Step 3: Handle the Return

After payment, the payer is redirected to your success_url or cancel_url.

Success URL parameters:

https://yoursite.com/payment/success?session_id=sess_abc123&payment_id=pay_xyz789

Cancel URL parameters:

https://yoursite.com/payment/cancel?session_id=sess_abc123

Step 4: Verify Payment

Always verify the payment server-side:

curl -X GET https://api.govpayplan.com/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

WARNING

Never trust client-side data alone. Always verify payment status via API or webhook.

Customization Options

Session Parameters

Parameter	Required	Description
amount	Yes	Payment amount
currency	Yes	Currency code (USD)
payment_type	Yes	Your configured payment type
description	No	Payment description shown to payer
reference_id	No	Your internal reference
success_url	Yes	Redirect URL after success
cancel_url	Yes	Redirect URL if cancelled
payer	No	Pre-fill payer information
metadata	No	Custom key-value data
expires_in	No	Session expiry (seconds)

Pre-filling Payer Info

{
  "payer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "address": {
      "line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345"
    }
  }
}

Custom Metadata

Store custom data with the payment:

{
  "metadata": {
    "permit_number": "12345",
    "applicant_id": "APP-789",
    "department": "Building"
  }
}

Page Customization

The hosted page automatically uses your agency branding configured in settings:

• Agency logo
• Colors
• Contact information

Session Lifecycle

Expiration

Sessions expire after:

• 24 hours (default)
• Custom expires_in value

States

State	Description
pending	Awaiting payment
completed	Payment successful
expired	Session timed out
cancelled	Payer cancelled

Error Handling

Common Scenarios

Payment Failed

• Payer is shown error message
• Can retry on the same page
• Webhook sent on final failure

Session Expired

• Payer sees expiration message
• Prompt to restart payment

Network Error

• GovPayPlan handles retries
• Payer sees friendly error

Testing

Use sandbox credentials and test card numbers:

Scenario	Card Number
Success	4242 4242 4242 4242
Decline	4000 0000 0000 0002
Require 3DS	4000 0000 0000 3220

Related Topics

• Embedded Forms - In-page payment forms
• Webhooks - Payment notifications
• Testing - Test environment guide