Verify that your Stripe platform account is eligible for Top-ups — Top-ups allow platforms to add funds from an external bank account directly to their Stripe balance independent of payment processing
Create a Top-up via POST /v1/topups with amount, currency, description, and statement_descriptor; Stripe will debit the default bank account on file for the platform
Retrieve the Top-up object to monitor its status; it transitions through pending → succeeded or failed; expected_availability_date indicates when funds will be available in the Stripe balance
Listen to topup.succeeded and topup.failed webhook events to trigger downstream workflows (e.g., releasing held transfers once platform balance is funded)
Cancel a pending Top-up via POST /v1/topups/{id}/cancel if the funds are no longer needed before the Top-up clears
Use Top-ups in conjunction with manual payout scheduling when your platform's payout obligations exceed charge-derived balance — for example, when running promotions or guaranteeing same-day payouts to connected accounts
Known gotchas
Top-ups are not available to all Stripe accounts and may require explicit enablement — check your platform Dashboard or contact Stripe support to confirm eligibility before building Top-up flows into your architecture
Top-up funds are added to the platform's Stripe balance, not directly to connected accounts; you still need to create transfers to route funds to connected accounts after the Top-up succeeds
Top-up amounts and frequency may be subject to limits depending on your platform's account standing and history — consult Stripe's documentation and your platform agreement for applicable limits rather than assuming unlimited top-up capacity
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp