Withdrawals

A withdrawal returns your workspace's unused prefund to your own registered payout details. The API can start and cancel a withdrawal, but it can never choose a destination — which is what makes the money-moving scope safe to automate.

Two scopes split reads from writes:

• wallet.read — quote a hypothetical withdrawal and list existing ones.
• wallet.withdraw — request or cancel one. Deliberately opt-in and separate, so a leaked read-only or ordering key can never trigger a payout.

The safety model, in one paragraph

Requesting a withdrawal never pays instantly: the amount leaves availableBalance immediately, but payout happens only after a business-day hold (payableAfterUtc). Until the moment it is paid, you can cancel and the funds return to your wallet. Destination, fee schedule, and hold length are workspace configuration — not request parameters — so the worst a compromised wallet.withdraw key can do is move your money to you, visibly, with a cancellation window.

Quote a withdrawal (wallet.read)

POST /api/v1/withdrawals/quotes

{ "amount": 100.00, "currency": "USD" }

{
  "amount": 100.00,
  "fee": 1.00,
  "net": 99.00,
  "currency": "USD",
  "payableAfterUtc": "2026-09-08T12:00:00Z",
  "availableBalance": 425.00
}

Quoting has no side effects — use it to show fees and the earliest payout instant before committing. availableBalance is your current headroom.

Request a withdrawal (wallet.withdraw)

POST /api/v1/withdrawals

{ "amount": 100.00, "currency": "USD" }

Returns 201 Created with the withdrawal:

{
  "id": "0198e111-2222-7abc-9def-333344445555",
  "publicReference": "wd_XXXXXXXX",
  "status": "Requested",
  "amount": 100.00,
  "fee": 1.00,
  "net": 99.00,
  "currency": "USD",
  "requestedAtUtc": "2026-09-05T12:00:00Z",
  "payableAfterUtc": "2026-09-08T12:00:00Z",
  "paidAtUtc": null,
  "cancelledAtUtc": null
}

Rejections: 400 invalid_request (bad amount/currency), 409 conflict when the amount exceeds your available balance or withdrawals are not configured for the workspace.

Quote publicReference when talking to support or matching bank statements.

Cancel before payout (wallet.withdraw)

POST /api/v1/withdrawals/{withdrawalId}/cancellation

{ "reason": "requested in error" }

Cancels a not-yet-paid withdrawal and returns the funds to availableBalance (200 OK with the updated row, status: "Cancelled"). A withdrawal that already reached Paid returns 409 — at that point the money is on its way to your registered details.

List withdrawals (wallet.read)

GET /api/v1/withdrawals?status=requested

Returns your workspace's withdrawals (optional case-insensitive status filter). Statuses:

Operational guidance

• Keep the wallet.withdraw key in your treasury tooling only, ideally CIDR-pinned; nothing customer-facing ever needs it.
• Reconcile Paid rows against your bank/settlement records by publicReference and net.
• A Requested row past its payableAfterUtc by more than a business day deserves a support ticket with the withdrawal id.