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 Apostra servers — Apostra 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. If you close or cancel the form before choosing Save card, no payment method is added. You can return to Payment & invoices and start again.

​

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 Apostra waits for authoritative server confirmation. Most cards confirm within seconds. If confirmation is delayed, Apostra 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. Apostra 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.

If Plan & Billing cannot load the confirmation status, it shows Unable to load card confirmation status with Try again instead of the add-card form, because a card you already submitted may still be confirming. If you have a saved card, it stays visible, but Replace is unavailable until the status loads. If your session has expired, you are asked to sign in again.

​

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, Apostra 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 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. This legacy URL can be reopened until the capture is verified or expires; it is not a one-time browser exchange.
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 Apostra API.

The agent then polls action: "status" (every 15–30 seconds is plenty) until the status is verified or expired. A verified capture is historical evidence: read the billing account’s current payment.paymentMethod before reporting an active payment authority. If the capture is expired, the legacy task requires a fresh request. The link statuses are pending → opened → verified, with expired as the terminal didn’t-complete state. For a private Partner Offer, this is the MCP continuation after the organization administrator accepts the exact Offer in open_iu_plan_task. Offer acceptance, verified card authority, and Partner operating authority are separate facts. After a verified capture, read the Partner access decision: purchased: true proves the contract-backed entitlement, while allowed: true also requires the organization’s owner claim, registration, current production certification readiness, usable payment standing, and no hold. Never send PAN, CVC, or a card token in an MCP tool argument.

​

V3 agents (save_billing)

On /mcp/v3, call get with { "kind": "billing" } to read the selected organization’s billing readiness, current Terms and payment status in either text or structured output. It omits card details and browser credentials. The billing read does not add a secure one-time cardholder handoff. paymentAuthority.secureHandoff.available is false. Existing save_billing integrations retain their request, confirm and status actions, permissions and response shapes. The legacy browser credential can be reopened until verification or expiry; it does not provide a one-time exchange with fresh human proof. Its continued availability does not complete the new secure text-only setup flow. Poll current readiness by repeating the billing read every 15–30 seconds. paymentAuthority.status and paymentAuthority.expiresAt describe the latest capture link, at the same path as the save_billing status poll; submission describes a submitted card form, including processing, verified, failed and expired outcomes. Only paymentAuthority.verified reports whether the canonical billing account currently has a verified payment method. A request, an opened browser page, and an old verified capture are not equivalent to that current state. Existing save_billing calls with { "paymentAuthority": { "action": "status" } } retain their capture-history response: method, status and expiresAt, with the existing payment_authority_pending, payment_authority_opened, payment_authority_verified or payment_authority_expired action. Existing permissions still apply, and no capture record returns NOT_FOUND. From a Buyer or Seller account, authorized organization admins can accept the current Terms through save_billing and verify the result with another billing read. Parent-container sessions can read readiness, but retain their existing write restriction; nextAction.canCompleteInChat is false. Follow the text-only billing flow for the read/write/read sequence and status fields. The new readiness flow stops before card setup. A versioned one-time handoff with fresh cardholder confirmation is still needed. Existing capture-link clients continue to use their deployed contract. Behind the legacy 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