Buy ONE period of continuity under a mandate the instrument proves. Nothing renews.
THE PAYMENT TOKEN IS THE SPENDING AUTHORITY (1.50.0): any active identity of the workspace may call this — including a provisional credential on an unclaimed workspace — and no capability has to be granted first, because the human who granted the token's mandate already delegated the spending. Idempotency-Key is REQUIRED: without it the request is refused 400 IDEMPOTENCY_KEY_REQUIRED. The mandate (limit, currency, expiry) is read from the instrument at Stripe and never from this body. Omit instrument to reserve the purchase and pay it later with POST /purchases/{id}/pay. ACTIVATION IS NEVER WRITTEN BY THIS ROUTE: a successful charge answers 200 with status payment_received and activated false, and the signature-verified payment_intent.succeeded webhook activates the period a moment later — read GET /purchases/{id} to see it active. Refusals: ALREADY_COVERED when the period is already paid for, PURCHASE_ALREADY_OPEN when one purchase is already open, MANDATE_INSUFFICIENT with the recorded verdict when the instrument does not carry the amount, and 503 MANDATE_UNVERIFIED with retry_after_seconds when Stripe could not be asked at all (nothing is charged and the purchase stays open). Every refusal carries missing as a list of { code, detail } with code one of no_instrument, over_limit, wrong_currency, expired, deactivated, unverified.
Request
- Base URL: https://forbiz.io/api/public/agent
- URL: https://forbiz.io/api/public/agent/purchases
- Auth: HTTP bearer
Headers
Recommended on every mutating request. A replay with the same key is NOT applied twice: the server answers { ok, idempotent_replay: true, first_seen_at, status } describing the first attempt.
Request body
Response
Payment received; the webhook activates the period
Changes
No recorded changes to this operation across all 1 revision of this API.