Dashboard Billing
Card checkout, payment confirmation and subscription renewals.
Dashboard billing
These routes use the authenticated dashboard session. Creating a checkout, viewing its signed form, changing billing details and cancelling renewal require an owner or admin. They are not part of the public agent API or MCP tool surface.
GET /v1/billing returns billing details and the current plan. A Redsys subscription past its paid period reports blocked=true and blockReason="payment_required" until renewal is confirmed.
Free trial
New accounts receive 20 free trial minutes, expiring 14 days after signup, with no card required. Calls are blocked when the allowance is exhausted or the trial expires. Existing accounts retain their previously granted trial terms.
Promotional signup and first-month minutes
https://app.orbitali.ai/promo accepts a code, or prefill it with
https://app.orbitali.ai/promo?code=VDS2026. Promotions are for brand-new users
creating their own first workspace; existing accounts and invitees are ineligible.
VDS2026 grants 120 total trial minutes for 28 days from workspace activation.
Signup must complete before October 26, 2026 at 00:00 Europe/Madrid
(2026-10-25T23:00:00Z). The campaign deadline stops new signups claiming the
offer; it does not shorten an already granted trial.
Subscribing before the trial's expiry transfers the unused promotional allowance to the first paid billing period only, in addition to the plan's minutes. For example, using 45 trial minutes leaves 75 extra minutes for the first paid period. The bonus expires at that period's end, with no rollover to renewals or later subscriptions. Checkout creation and browser redirects do not transfer minutes: the existing verified payment confirmation activates the paid period. Calls that started during the trial reduce its remaining allowance even when their duration is finalized after subscription activation.
GET /v1/billing returns optional plan.promo with code, trialExpiresAt,
converted, bonusMinutes, and bonusExpiresAt. bonusMinutes is the total
bonus allocated to the current period, not its remaining balance. It is zero
outside that period. plan.includedMinutes includes the active bonus and may be
fractional because calls are billed in ten-second intervals; plan.plan.includedMinutes
remains the plan's base allowance. Usage allocation and overage billing use the
same bonus.
The signup page uses unauthenticated POST /v1/auth/promo with
{ "code": "VDS2026" }. Codes are trimmed and case-insensitive. A successful
response contains code, minutes, trialDays, signupExpiresAt, and a signed
signupToken intended only for the signup flow. Invalid format returns
400 PROMO_INVALID; unknown, disabled, or expired codes return
404 PROMO_UNAVAILABLE. Validation does not reserve the offer past its deadline.
This endpoint is part of dashboard signup, not the public agent API or MCP.
Campaigns are stored in promo_codes, with immutable granted terms in
promo_redemptions. Organization data exports include redemptions; account
deletion removes them. A retained aggregate of consumed billing intervals
prevents call retention/deletion from restoring spent promotional minutes.
Start or change a plan
POST /v1/billing/plan-checkout-sessions
{ "plan": "studio", "recurringConsent": true }
An initial Redsys purchase requires recurringConsent=true, corresponding to the displayed authorization for monthly plan charges and usage overages. The response is either:
{ "outcome": "checkout", "provider": "redsys", "checkoutUrl": "https://app.example/billing/checkout/redsys/ORDER_UUID" }
or outcome="scheduled", plan and effectiveAt for a change to an existing subscription. Checkout providers are redsys, stripe, or mock (development only). Existing Stripe subscriptions stay on Stripe. A Redsys plan change takes effect only after the renewal payment succeeds.
409 can indicate billing_profile_incomplete, recurring_consent_required, checkout_already_pending, subscription_already_exists, or payment_requires_review. Incomplete or disabled payment configuration returns 503 payment_provider_unavailable. Do not interpret every 409 as a missing billing address.
Checkout status
GET /v1/billing/redsys/checkouts/:id returns the current organization's order: id, kind, status, environment, amountCents, overageCents, the immutable terms, consentAccepted, bank form action, and signed fields only while pending after consent. The form never contains a stored card reference. Status is one of pending, processing, paid, declined, review, expired. Responses are not cached. The signing secret is never returned.
POST /v1/billing/redsys/checkouts/:id/consent accepts:
{ "accepted": true, "version": "monthly-plan-and-usage-v2" }
The owner/admin must first see the returned terms (monthly amount, included usage, rates, rounding and cancellation). Acceptance records the account, immutable terms and timestamp once. Creating the order with recurringConsent=true does not itself issue a bank form. Expired forms already issued require reconciliation before another order can be created.
POST /v1/billing/redsys/payment-method accepts the same body and returns a hosted checkout for card authentication (operation 7). It requests a fresh reference, never exposes the old one, and never grants a paid period or restarts a failed renewal.
POST /v1/billing/redsys/recovery accepts the same body and creates a fresh customer-authenticated checkout for a definitively declined renewal. The subsequent consent endpoint is still required. It is blocked for pending/ambiguous results, cancelled subscriptions and non-repeat bank responses; these need support review. A confirmed recovery collects the original failed amount (one monthly fee plus prior usage), starts one month from confirmation, and does not collect skipped monthly fees. There are no automatic retries.
GET /v1/billing also returns optional provider and latestPaymentId for status/recovery UI. Billing mutations and Redsys order reads require owner/admin access to that organization.
The hosted TPV accepts cards only. The return page waits for bank confirmation. A successful redirect does not establish payment success.
Notifications and cancellation
POST /v1/billing/redsys/webhook accepts form-encoded Ds_SignatureVersion, Ds_MerchantParameters and Ds_Signature. It does not use dashboard authentication; authentication is the verified bank signature and the stored order match. Duplicate notifications do not create another billing period. Responses are 200 OK after processing, 400 ERROR for invalid notifications, or 500 ERROR for processing failure.
POST /v1/billing/subscription/cancel-renewal cancels future renewal with the subscription's existing provider. Redsys access continues through the paid period and any final usage overage is settled separately. Uncertain or declined renewal charges require support review and are not automatically charged again.
Operational evidence and privacy
Bank outcomes retain only response/authorization codes and timestamps in the payment audit trail. No PAN, CVV, raw bank payload, or reference is included in exports or the operator listing. Organization exports include orders, terms and payment-event summaries. Deletion is blocked for unresolved payments and production Redsys history until a financial retention/archive policy is approved; the DSR erase path enforces the same guard under the account lock.
Reconciliation and refunds are performed in the bank portal and recorded with scripts/redsys-operations.ts by a privileged billing operator. This tool records evidence; it does not send bank operations or grant access. See the repository's docs/redsys-local-testing.md for commands and activation prerequisites.
Restricted live verification
The Redsys checkout response can also have kind: "live_test". This is an operator-created, account-restricted EUR 10 verification payment, with no subscription change, card storage or renewal. No public creation endpoint is provided. Existing checkout authentication, roles and signed notification validation still apply. A successful browser return is not payment confirmation.