Paying by card

Adding a card gives your organization a payment method for eligible platform and IU charges. You save it once on the Plan & Billing page, and it becomes your organization’s payment method — there is no checkout step, no plan you must pick first, and no commitment.

​

What “add a card” does

When an org admin adds a card on Settings → Plan & Billing → Payment & invoices:

1. The card details are collected in a secure form embedded in the page. Card numbers are encrypted in transit and never stored on Scope3 servers — Scope3 keeps only the card’s brand, last four digits, and expiry date, for display.
2. If your bank requires it, a quick verification step happens right in the form (you may recognize this as the confirmation prompt your bank uses for online purchases).
3. Once verified, the card becomes the organization’s payment authority. Saving it does not by itself accept an IU Rate Card, select a plan, or turn on paid entitlements.

The card belongs to the organization, not to the person who added it. Only org admins can add, replace, or remove it.

​

While card confirmation is processing

After you submit the secure card form, Plan & Billing shows Card confirmation in progress with the submission time. This processing state is saved for the organization, so it remains visible if you close the panel, refresh, navigate away, or sign out and return later. You can safely leave the page while Scope3 waits for authoritative server confirmation. Most cards confirm within seconds. If confirmation is delayed, Scope3 checks the payment processor directly so a delayed or missed notification can still converge. While an unexpired confirmation is processing, Plan & Billing does not offer a second indistinguishable card submission. The processing attempt is not a payment method: it cannot be charged, grant entitlement, or replace a verified card. When replacing a card, the existing verified card remains active until the new card is confirmed. The saved state then changes to one of these outcomes:

• Verified — the card’s display-safe brand, last four digits, and expiry replace the processing state.
• Failed — Plan & Billing explains that the card could not be confirmed and offers Try another card. Scope3 does not expose raw processor or bank errors.
• Expired — confirmation did not reach a terminal result within 30 minutes; Plan & Billing offers a fresh attempt.

​

When the card is charged

Nothing is charged when you add the card. Automatic charging starts only when your organization has an accepted IU Rate Card and the applicable charging rollout is enabled. A plan commitment may be charged at cycle start; usage and overage are charged after they accrue according to the accepted Rate Card. A fee invoice records each issued charge. There are no card processing fees added to what you pay. If your organization would rather receive invoices and pay on net terms — purchase orders, AP portals, bank transfer — that path is always available: choose Set up invoicing instead. Both paths lead to the same Plan & Billing page, and you can switch between them later. Larger organizations often pick the card too: it skips vendor setup on both sides.

​

If a payment fails

If a charge fails, Scope3 retries automatically on a published schedule. It emails the initial failure, failed-retry warnings, and the payment-hold notice; there is no separate day-30 email in the current alpha: The hold is currently a billing-status and operations signal, not an authorization gate. It does not pause new intelligence-credit spend, media commitments, subscriptions, or upgrades. The intended future restriction model would preserve access to:

• Your data, reports, and dashboards
• Data export
• Media that is already delivering (a card hiccup never pauses delivery mid-flight — that would create make-goods and harm the seller)
• This page and updating your card — the fix-your-card flow is never gated by the problem it exists to fix

Payment recovery is self-serve. Update your card, then either wait for the next automatic retry or click Update card & pay now to retry immediately. A successful charge resolves the dunning case and removes its recorded hold; because the current alpha does not enforce that hold at authorization call sites, this is payment-state recovery rather than access restoration. The timings above come from the card-rail’s global dunning configuration; they are not adjusted per account today.

​

Updating or removing the card

• Replace — add the new card the same way; it becomes the payment method and the old one is discarded. Do this any time, including before the old card expires.
• Expiry — when your bank reissues a card, the saved card usually updates automatically with no action from you. When it can’t, Plan & Billing shows an “expires soon” badge and you get an email about 30 days before the expiry date — a heads-up, not a restriction: an expiring card with no failed charge never blocks anything on its own.
• Remove — allowed when nothing depends on the card. If it is your organization’s only way to pay, removal is blocked with a pointer to add a replacement first (or set up invoicing). This preserves a valid payment path; card removal does not itself change entitlements.

​

For agents

The saved payment method appears in the billing account document as payment.paymentMethod — kind, brand, last four digits, expiry, and status. When an organization has no payment method and needs one, the document’s nextAction is ADD_PAYMENT_METHOD. Card entry itself is always a human step (it happens in a secure form), so agents hand that moment to a person — and there is a dedicated task for exactly that handoff.

​

Requesting a card via your agent (add_payment_authority)

An agent working on the organization’s behalf requests a payment method with the add_payment_authority MCP task, in three steps:

1. Request — call with action: "request". The task stages the request and returns a single-use confirmationToken (valid 5 minutes). Nothing is created yet.
2. Confirm — call again with action: "confirm" and that token. The task returns { method: "capture_link", url, status, expiresAt } — a secure link valid for 30 minutes that serves one verified card capture. The URL is returned exactly once; the agent saves it and hands it to the person who holds the organization’s card.
3. The cardholder opens the link in any browser — no account or sign-in is needed; the link itself is the authorization. The page shows which organization requested the card and the same secure embedded form as Plan & Billing. Card details go directly to the payment processor and never pass through the agent or the Scope3 API.

The agent then polls action: "status" (every 15–30 seconds is plenty) until the status is verified — at which point the organization has an active payment authority (but no entitlement or plan change) — or expired, in which case it requests a fresh link. The link statuses are pending → opened → verified, with expired as the terminal didn’t-complete state.

​

V3 agents (save_billing)

On the account-resolved /mcp/v3 surface, use the shared save_billing tool. It delegates to the same confirmation store, capture-link service, hosted page, and organization authorization rules as add_payment_authority:

1. Call { "paymentAuthority": { "action": "request" } }.
2. Call again with { "paymentAuthority": { "action": "confirm", "confirmationToken": "..." } }.
3. Give the returned paymentAuthority.url to the cardholder.
4. Poll { "paymentAuthority": { "action": "status" } } every 15–30 seconds.

The V3 wrapper returns confirmation_required before confirmation, human_action_required with the newly issued URL, then payment_authority_pending, payment_authority_opened, payment_authority_verified, or payment_authority_expired while polling. It accepts no card-number, security-code, payment-processor-secret, or bank field. Card collection must be enabled for the organization. Behind the capture page sits one public endpoint, GET /api/v2/capture-links/{token}: the hosted page exchanges the link token for the embedded form’s credentials (and marks the link opened), and polls it with ?view=status while verification completes. The token is the sole authorization — unknown tokens return nothing about any organization, and requests are rate-limited. Requesting a link requires org-admin access or an org-scoped service token; the task is available on both the buyer and legacy v2 storefront MCP servers because Plan & Billing is org-level regardless of role. Two more nextAction values cover the failure/recovery path above:

• RESOLVE_HOLD — a payment-failure hold is recorded (day +10 in the table above). The current alpha does not enforce it as an authorization gate. Resolved by POST /api/v2/billing/payment-methods/pay-now, which retries the outstanding charge on the org’s saved card immediately. The route returns processing; poll the billing account document and watch nextAction/standing.holds for confirmation rather than inferring success from the response (the actual recovery is confirmed server-side, asynchronously).
• UPDATE_PAYMENT_METHOD — a soft nudge shown when the card is inside the expiry lookahead window. It never gates anything on its own; it resolves the same way as ADD_PAYMENT_METHOD (replace semantics).

standing.holds on the billing account document lists any active holds — today only PAYMENT_FAILED — each with a reason and createdAt.

​

Related