Customer Portal

Overview

The Xtopay Customer Portal is a hosted page where your customers can:

• View current subscriptions and billing history
• Download invoices
• Update payment methods (card, mobile money)
• Upgrade or downgrade their plan
• Cancel or pause their subscription
• Update billing address and contact details

You don't build any of this UI. You create a portal session server-side and redirect the customer there.

Create a portal session

const session = await xtopay.customerPortal.createSession({
  customer_id: "cus_a1b2c3",
  return_url: "https://yourapp.com/account",
});

redirect(session.url);
// https://billing.xtopay.co/portal/sess_...

Portal sessions expire after 30 minutes. Create a new session each time a customer wants to access the portal — don't cache the URL.

Typical integration

// In your account settings page
export async function GET(req: Request) {
  const userId = await getAuthenticatedUserId(req);
  const user = await db.users.findUnique({ where: { id: userId } });

  const session = await xtopay.customerPortal.createSession({
    customer_id: user.xtopay_customer_id,
    return_url: `${process.env.APP_URL}/account`,
  });

  return redirect(session.url);
}

// Account page button
<a href="/api/portal" className="btn btn-secondary">
  Manage billing
</a>

Customising the portal

Configure portal behaviour in Dashboard → Settings → Customer Portal:

• Logo and colours — match your brand
• Allowed actions — choose which self-service actions to enable/disable
• Plan visibility — control which plans customers can switch to
• Cancellation flow — optional cancellation survey and pause-before-cancel prompt

Webhook events from the portal

Customer actions in the portal fire the same webhooks as API actions: