Hosted pages

Hosted Checkout

When customers need to upgrade to or purchase a paid plan, they’re directed to a hosted checkout page.

Supported Payment Providers

Stripe - Currently supported
More payment providers coming soon

Features

Feature	Description
Secure payment processing	PCI-compliant payment handling
Plan selection	Display multiple plan options
Purchase types	One-time and recurring payments
Mobile-responsive	Works on all devices
Branded experience	Your logo, colors, and fonts

How Checkout Works

Customer clicks an upgrade link or uses the upgrade_plan virtual tool
SolvaPay generates a checkout session with available plans
Customer selects a plan and enters payment details
Payment is processed through your connected Stripe account
The success screen appears once the payment is confirmed
Customer is redirected back to their MCP client

The success screen is gated on the actual payment confirmation — it never shows while Stripe is still processing the charge, so a refresh cannot surface a still-processing payment as complete.

Credit top-ups

Pay-as-you-go plans use a hosted top-up page where customers choose an amount and pay to add credits.

Change amount — after continuing to payment, customers can go back with the ← Change amount link to pick a different amount. The entered amount is preserved.
Business purchases — customers buying as a business can enter their company name, country, and tax identifier (VAT number or EIN) directly on the top-up page. Stripe Tax calculates the correct tax — including reverse charge for eligible EU cross-border B2B purchases — and the final amount updates before the customer confirms. Business details are saved on the customer, so returning buyers don’t re-enter them.
Confirmed success — like checkout, the top-up success screen waits for the payment confirmation before showing, and credits are minted when the charge succeeds.

Upgrade via Virtual Tools

AI agents can help users upgrade using the built-in virtual tools:

User: "I need access to the advanced search feature"

Agent: [calls upgrade_plan tool]

Response: "To access advanced search, you'll need the Pro plan. 
Here's your upgrade link: https://..."

The upgrade_plan tool returns:

Available plans that include the requested feature
Checkout URLs for each plan
Plan details (price, features, quotas)

Customer Account Portal

Customers can manage their purchases through a self-service portal without contacting support.

Portal Capabilities

Action	Description
View purchases	See active plans and details
Billing information	View cycle and next payment date
Cancel renewal	Access continues until billing period ends
Reactivate	Resume cancelled purchases
Transaction history	View past payments

Accessing the Portal

Customers can access the portal via:

Direct link - Generate a secure session link programmatically
Virtual tool - The manage_purchase tool returns a portal URL
Email links - Include in billing emails

Portal Session Security

Portal sessions are:

Time-limited for security
Tied to the authenticated user
Accessible without re-entering payment details

Provider Branding

All customer-facing pages display your brand identity. No SolvaPay branding appears on these pages.

Customizable Elements

Configure these in Settings > Hosted pages:

Element	Description
Brand name	Displayed in headers and page titles
Logo	Shown on checkout and login pages
Accent color	Used for buttons and highlights
Font family	Choose from multiple web fonts
Light mode colors	Color palette for light theme
Dark mode colors	Color palette for dark theme

Legal links

Add your Terms of Service URL and Privacy Policy URL in Settings > Hosted pages. Hosted checkout, sign-in, and OAuth consent then link those documents in the consent sentence, followed by SolvaPay’s own terms. SolvaPay links also stay in the page footer. Leave either field empty to omit that merchant document from the sentence.

Theme Adaptation

Pages automatically adapt to the user’s system preference:

Light mode - Uses your light color palette
Dark mode - Uses your dark color palette

Users see a consistent experience that matches their system settings.

Logo Requirements

For best results, upload a logo that:

Has a transparent background (PNG recommended)
Is at least 200px wide
Works on both light and dark backgrounds

If your logo doesn’t work on both backgrounds, consider uploading separate versions for light and dark modes.

Virtual Tools Reference

Managed MCP injects these tools into every server for purchase management:

`get_user_info`

Returns the current user’s purchase information. Response includes:

User ID and email
Current plan name and ID
Purchase status (active, cancelled, past_due)
Quota usage and limits

Use case: Let AI agents check user status before attempting protected operations.

`upgrade_plan`

Returns available upgrade options for the user. Response includes:

List of available plans
Plan details (name, price, features)
Checkout URLs for each plan

Use case: Help users discover and upgrade to plans that include features they need.

`manage_purchase`

Returns a URL to the customer billing portal. Response includes:

Secure portal session URL
Session expiration time

Use case: Let users manage billing, cancel, or reactivate without leaving their workflow.

Integration Examples

Handling Paywall Responses

When a user lacks access to a tool, the proxy returns a paywall response. AI agents can use virtual tools to help:

User: "Export my data to CSV"

Agent: [calls export_to_csv tool]

Proxy: "Access denied - requires Pro plan"

Agent: [calls upgrade_plan tool]

Agent: "The CSV export feature requires a Pro plan ($19/month). 
Would you like to upgrade? Here's the link: [checkout URL]"

Proactive Quota Warnings

Agents can check usage before it becomes a problem:

Agent: [calls get_user_info tool]

Response: { quota_used: 95, quota_limit: 100 }

Agent: "You've used 95 of your 100 monthly API calls. 
Consider upgrading to Pro for 10,000 calls/month."

Customization Limits

While branding is fully customizable, the page layouts and flows are managed by SolvaPay for:

Security compliance
Consistent user experience
Automatic updates and improvements

For advanced customization needs beyond branding, consider the SDK integration approach which gives you full control over the user interface.

Next Steps

Best practices - Plan configuration and quota strategies
Authentication - Learn about OAuth and user sessions

Get started

Guides

Managed MCP

Plans and billing

Webhooks

Admin MCP Server

Changelog

Hosted Checkout

Supported Payment Providers

Features

How Checkout Works

Credit top-ups

Upgrade via Virtual Tools

Customer Account Portal

Portal Capabilities

Accessing the Portal

Portal Session Security

Provider Branding

Customizable Elements

Legal links

Theme Adaptation

Logo Requirements

Virtual Tools Reference

`get_user_info`

`upgrade_plan`

`manage_purchase`

Integration Examples

Handling Paywall Responses

Proactive Quota Warnings

Customization Limits

Next Steps

​Hosted Checkout

​Supported Payment Providers

​Features

​How Checkout Works

​Credit top-ups

​Upgrade via Virtual Tools

​Customer Account Portal

​Portal Capabilities

​Accessing the Portal

​Portal Session Security

​Provider Branding

​Customizable Elements

​Legal links

​Theme Adaptation

​Logo Requirements

​Virtual Tools Reference

​get_user_info

​upgrade_plan

​manage_purchase

​Integration Examples

​Handling Paywall Responses

​Proactive Quota Warnings

​Customization Limits

​Next Steps

Hosted Checkout

Supported Payment Providers

Features

How Checkout Works

Credit top-ups

Upgrade via Virtual Tools

Customer Account Portal

Portal Capabilities

Accessing the Portal

Portal Session Security

Provider Branding

Customizable Elements

Legal links

Theme Adaptation

Logo Requirements

Virtual Tools Reference

`get_user_info`

`upgrade_plan`

`manage_purchase`

Integration Examples

Handling Paywall Responses

Proactive Quota Warnings

Customization Limits

Next Steps