Open a stripe-hosted card page
well_create_hosted_payment_linkOpen a Stripe-hosted page for one of three card moments: add_card (a new card), recollect_card (a card group-3 of well_list_payment_cards saved by another person, which must be re-entered on this workspace's own Stripe customer before it can charge here), or complete_authentication (a bank's 3-D Secure check).
Returns url, a link on checkout.stripe.com, billing.stripe.com, hooks.stripe.com or invoice.stripe.com; expires_at, when the page stops working; and then, the tool to call once the user is back (well_list_payment_cards). Hand the url to the widget or open it; never type it into the conversation, never ask for or relay what the page itself collects (a card number, an expiry, a security code), and never read it back from a tool result — this tool returns no card data by design, so there is none to relay.
complete_authentication is refused with authentication_unavailable for now: Well holds no billing offer whose charge the page could finish. Give the bank-check link the payment receipt carries instead, or send the owner to the billing page.
Only a workspace owner or admin opens a hosted payment link. error_reason: missing_key (recollect_card without card_ref, or complete_authentication without offer_id), no_membership (the caller has no active membership in the workspace, or no workspace is in context), not_admin (the caller is a member but not an owner or an admin), authentication_unavailable (see above), billing_off (billing is not active on this Well instance), no_customer (the workspace has no Stripe customer yet; send the owner to the billing page first), failed (Stripe did not return a session).
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| purpose | Yes | add_card: the workspace adds a new card. recollect_card: a card group-3 of `well_list_payment_cards` saved by another person must be re-entered on this workspace's own Stripe customer. complete_authentication: a bank's 3-D Secure check must finish before a charge or a saved card is usable. | |
| card_ref | No | Required for recollect_card: the opaque cardRef `well_list_payment_cards` gave for the card being re-entered. | |
| offer_id | No | Required for complete_authentication: the offer_id of the billing offer that needs the bank check. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A Stripe-hosted page. Open it as given; never read, repeat, log or store anything the page itself holds. | |
| then | No | The tool to call once the user says they are back from the page. | |
| error | No | ||
| success | Yes | ||
| expires_at | No | When the page stops working, as an ISO timestamp; null when Stripe gave no expiry. | |
| error_reason | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |