---
title: "Create a hosted top-up checkout session"
method: POST
path: "/v1/wallet/topup/sessions"
tags: ["Wallet"]
---

# Create a hosted top-up checkout session

`POST /v1/wallet/topup/sessions`

Creates a hosted Stripe checkout session and returns the session id and redirect URL. This is the funding path advertised by the `WALLET_INSUFFICIENT_FUNDS` 402 and by `GET /v1/wallet/balance` (`topup.stripe`): an agent creates the session and hands `url` to its human owner to pay.

## Request body

- WalletTopupRequest
  - `amount` number, required — Top-up amount in dollars (float).
  - `currency` 'USD', required — Top-up currency (currently only USD).
  - `success_redirect` string — Where to send the payer after a successful checkout. Must be on the Monid web-app origin. Defaults to the web-app wallet page, so an agent without a UI can omit it and hand the returned `url` to its owner.
  - `cancel_redirect` string — Where to send the user if checkout is cancelled. Must be on the Monid web-app origin.
  - `autoReload` boolean — Opt in to auto-reload (with the service defaults) when this checkout completes. Opt-in ONLY: the system never enables auto-reload on the caller's behalf, so `false` and an omitted field are equivalent and record nothing. Ignored when auto-reload is already enabled on the wallet.

## Response `200`

Checkout session created

- WalletTopupSessionResponse
  - `paymentProcessor` string, required — Payment processor type (e.g. STRIPE).
  - `sessionId` string, required — Hosted checkout session id.
  - `url` string, required — Hosted checkout redirect URL.

## Other responses

- `400` — Bad request — input failed validation
- `401` — Unauthorized — missing or invalid credentials
- `403` — Forbidden — caller has no workspace or no access
- `500` — Internal server error
- `503` — Wallet not ACTIVE (provisioning, failed, or being set up). Transient states include a Retry-After header (seconds).

## Changes

- **2026-09-25** `5abada71ceae` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/monid/apis/monid-api/changes/v1/wallet/topup/sessions/post.md)

---

[API](https://skmtc.dev/monid/apis/monid-api.md) · [All operations](https://skmtc.dev/monid/apis/monid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/monid/apis/monid-api/revisions/5abada71ceae?raw)