payment_action describing what to do next, and the portal opens it. Credits and payment records are written by the provider’s webhook once the money actually moves, never optimistically on the customer’s screen.
The API examples on this page return to your own front end at
portal.yourapp.com. Their checkout_return query parameter is an application-defined example, not a Flexprice requirement. The hosted Flexprice portal uses returned=1 for its session-restoration flow. If you build your own portal, handle the return in your application.
Prerequisites
Portal payment actions require a payment provider connection published in the environment the session token was issued in. Without one, the portal renders its read-only surface and hides the payment actions.2
Check the capability you need is supported
Not every provider supports every action. See the capability matrix below.
3
Enable the portal sections
In Settings, turn on the sections that carry the actions. See Portal configuration.
Provider capabilities
Flexprice names each payment operation as a capability and resolves the provider per capability from the connections published in the environment. A capability is what Flexprice implements for that gateway, not everything the gateway’s own API can do.
Read the capabilities available to a session from
GET /v1/customer/portal/integrations:
is_default marks the provider Flexprice picks for that capability when the caller names none.
When exactly one provider serves a capability, the portal never shows its name to the customer. A provider picker appears only when two or more connected providers can serve the same action.
Paying an invoice
An invoice row in the Invoices section carries a Pay now action when the invoice is awaiting payment. The customer clicks it and continues to hosted checkout in the same tab. When the portal is embedded in an iframe, checkout opens in a new tab instead. The invoice is marked paid by the provider’s webhook when the payment settles. Endpoint:POST /v1/customer/portal/invoices/{id}/pay
Response:
payment_action rather than reaching for a URL field of your own. Whether a provider hands back a hosted checkout page or a payment link is a property of the provider, and the type says which.
The amount comes from the invoiceThere is no amount field in the request. A customer cannot part-pay an invoice from the portal.
When Pay now is not available
The API rejects a payment and the portal disables the action when:- The invoice is still a draft, or is voided
- The invoice payment status is already
succeeded, or a payment is already in flight - The invoice belongs to a subscription that is not in a state that allows collection. The portal shows a message asking the customer to contact support

Topping up a wallet
Add credits on the Credit balance card, or on the Credits tab, opens a top-up dialog. The customer picks a preset or enters a credit amount, chooses how to pay under Pay with, and sees the exact charge on the confirm button (for example Pay US$500.00) before continuing. Endpoint:POST /v1/customer/portal/wallets/{id}/top-up
Charge now or invoice later
Thecheckout object decides which of the two flows runs.
The portal always sends
checkout. The invoiced path is available to your own integrations calling the portal API directly.
Credits land after the payment, not on the clickThe portal reports “Top-up requested, your balance will update once payment completes” rather than claiming success. The wallet transaction is written by the provider’s webhook. After a return, the portal rechecks the balance on a short schedule (immediately, then at 1.5s and 4s) and stops as soon as the wallet actually changes, so a webhook arriving a moment after the redirect still shows up without a manual refresh.
Paying with a saved card
Whenuse_saved_method is true, the charge runs against the card on file with the customer present, and no redirect is involved. The response comes back with checkout_status: "completed" and no payment_action.
Read checkout_status, not the presence of a URL:
If no usable saved method exists, or the charge declines, the response falls back to a
payment_action with a link. The portal shows the saved-card option only when the resolved provider supports auto_charge and a chargeable card is on file.
Minimum top-up amount
Top-ups below the tenant’s per-currency floor are rejected before the customer is redirected, with a message naming the minimum for that currency. Configure the floor under thewallet_topup_config setting key. See Settings.
A top-up already in flight
If the customer already has a pending top-up session on the wallet, the API hands back the session already in flight rather than a conflict. The customer can complete the payment they started instead of being blocked by an abandoned tab.
Auto top-up
Auto top-up refills the wallet without the customer present. It reads as a plain-language summary in the Credits section: “Automatically add $100.00 when your balance falls below $20.00”, with a Manage action, or “Auto top-up is off” with Enable. Endpoint:PUT /v1/customer/portal/wallets/{id}/auto-topup
Clearing a cooldownSend
{ "value": 0, "unit": "hour" } to remove a stored cooldown. Sending null reads as an absent field on the server and leaves the existing cooldown in place.Requirements
Auto top-up needs a saved card that can be charged off-session. The portal shows “Add a payment method to enable automatic top-ups” and keeps the toggle unavailable until one exists, which means:- The resolved provider supports the
auto_chargecapability (Chargebee or Razorpay) - The customer has at least one saved card with
can_auto_charge: true

Saved payment methods
The payment methods list sits on Overview, beside the balance it tops up and the subscriptions it pays for. It shows each saved card as brand and last four digits with its expiry, marks the default, and offers Add card, plus Make default and Remove card in each card’s ⋯ menu. List:GET /v1/customer/portal/payment-methods
Adding a card
Endpoint:POST /v1/customer/portal/payment-methods
Setting a default and removing
Make default:POST /v1/customer/portal/payment-methods/default with payment_provider and payment_method_id.
Remove card: POST /v1/customer/portal/payment-methods/delete with the same two fields. The portal confirms first, warning that the card will no longer be available for payments or automatic top-ups.
Setting a default requires the set_default_method capability. On a provider without it, the portal explains that a default card is not supported rather than offering an action that would fail.

Returning from a hosted checkout
The standalone portal sends the customer to hosted checkout in the same tab and restores their portal session on return. An embedded portal opens checkout in a new tab because providers do not allow their payment pages to be framed. The portal resolves this itself:- The return URL keeps the portal path but removes the session token and unrelated query parameters. It adds a
returned=1marker, so the token is not sent to the provider as part of that URL. - Before leaving, the portal saves this tab’s token in
sessionStorage. A same-tab return restores that token even if the provider drops the return marker. A marked return in another tab can restore the shared token saved inlocalStoragefor up to one hour; this does not extend the session’s server-side expiry. - The portal restores the token in its address and renders the account again. It does not depend on closing a tab or a
BroadcastChannelannouncement. When a checkout session ID is available, it checks the session through the API and refreshes portal data after settlement. - If no session can be restored, the page asks the customer to return to their billing portal. A gateway-reported success shows You’re all set!; a reported failure or an unspecified result does not claim that payment succeeded. The provider’s webhook settles the payment independently of this page.
GET /v1/customer/portal/checkout-sessions/{id} returns the session with its checkout_status, failure_reason and linked checkout_invoice_id and checkout_payment_id. POST /v1/customer/portal/checkout-sessions/{id}/cancel abandons one.
Chargebee as a portal provider
Chargebee is the only connected provider that currently serves every portal capability, including saved-card management and default-card selection. Alongside the portal work, Chargebee invoice sync now pushes Flexprice invoices to Chargebee for collection and reconciles payments back through the Chargebee webhook, so an invoice paid on either side settles on both.Chargebee invoice sync
Troubleshooting
Related resources
Customer Portal
Sessions, sections and the security model
Portal configuration
Control which sections and actions appear
Portal API reference
Every endpoint under /v1/customer/portal
Autopay mandates
Mandates behind unattended charging

