Skip to main content
The @solvapay/react components (checkout, top-up, plans, balance, renewals, auto-recharge, history) call a set of routes on your backend: /api/check-purchase, /api/create-payment-intent, /api/list-plans and so on. solvapay.web.routes() serves all of them from Python, with the same answers as the TypeScript SDK: a shared conformance suite checks both on every change. Your React app doesn’t change. Only the backend behind /api is Python.

Prerequisites

  • A SolvaPay product with at least one plan, and a sandbox secret key in SOLVAPAY_SECRET_KEY. See Installation.
  • A web app that signs its users in. The routes act for the user your app has verified; they never sign anyone in themselves.
  • The React components set up in your frontend. See the React guide.

Serve the routes

Mount routes() where your frontend expects them, /api by default. get_user is required: it verifies the request with your app’s own auth and answers who the user is, or None.
This example verifies an HS256 token your app issued. Use whatever your app already trusts: a session cookie, your identity provider’s tokens, or a framework dependency. get_user may be async. In FastAPI, mount the same app:
The routes are a mounted Starlette app, so FastAPI dependencies don’t run for them: get_user gets the plain Starlette Request. If your app checks users with a dependency such as Depends(current_user), call the function behind it from get_user instead. base_path is where the routes sit below the mount point. Mounted at /api, it’s ""; served at the root, keep the default /api.

Point the React components at it

SolvaPayProvider sends your app’s token on every call through an auth adapter. The token is the one get_user verifies:
Serve /api from the same origin as the page (a reverse proxy, or your dev server’s proxy). The routes add no CORS headers; for a cross-origin frontend, add Starlette’s CORSMiddleware.

Who the customer is

  • Only get_user decides. Your user’s id becomes the SolvaPay customer’s externalRef. The customer is created on first use, with the email and name you return.
  • No user, no access. None gets a 401 before SolvaPay is called. There’s no anonymous or default customer.
  • Nothing the browser sends is identity. An x-user-id header is ignored. A cached x-solvapay-customer-ref is used only when that customer belongs to the verified user.
  • Purchases are checked. Cancelling or reactivating a renewal works only on the caller’s own purchase (403 otherwise), and auto-recharge is always saved for the caller’s own customer.
merchant, get-product and list-plans answer without a user, as in TypeScript.

Routes

Another path answers 404, and a known path with the wrong method answers 405 with Allow.

Where Python differs

On paths no shared case covers, Python fails where TypeScript carries on:
  • A failed customer read in check-purchase is an error, not an empty purchase list.
  • A failed balance read during a top-up fails the request.
  • A body that isn’t a JSON object gets 400 Invalid JSON body.
The full list is in the conformance suite’s Known divergences.

Example

examples/react-web-checkout runs one React app against a Python and a Go backend. Checkout, top-up, renewals, auto-recharge and history were tested on both in sandbox.