Payments plugin setup

This plugin is Botseon's own, not a vendor's: it asks a member to approve one purchase and then pays for it with a single-use card locked to that merchant. So, unlike every other page here, there is no OAuth app to create in somebody else's console and no key to paste. What it needs instead is two things, and until both are in place the plugin does nothing at all.

What it needs

1. A card issuer configured for this deployment. Issuing a card is a contracted relationship with a card issuer, and the implementation of that relationship is not part of this Apache-2.0 framework (the same licence seam the billing adapter sits behind). No edition of this repository ships one, so on a deployment built from this tree the answer is always "no issuer".
2. Payments turned on for the organisation. An admin switch, and it is off until an admin turns it on. A deployment with an issuer still spends nothing for an organisation that has not asked for it.

Both values are read on every path that could expose the capability, so there is no order to get right and no step that half-enables it:

The sentence a member reads in all four places is one string (packages/core/src/payments.ts), so it cannot say one thing on the card and another in a run.

What the plugin does once both are in place

Two tools, and the first of them cannot run without a person:

• payments.request_spend — asks for one amount at one merchant. It is tagged spend (and external_send); spend means the approval engine always raises a card for it, no saved rule can ever release it, and a run that has read untrusted content cannot reach it at all (see ../reference/permission-tags.md). The card a member answers names the amount, the merchant as an origin (never as a link), what the bot says the purchase is for, the ceiling the card will carry, what is left of today's limit, when the card expires, and whether this bot has ever bought from that merchant before.
• payments.card_status — reads back what became of a card this bot was issued: its state, its remaining headroom and when it expires. A separate grant from the one that lets a bot spend, so a connection given read access cannot spend.

Per-bot enablement is a grant like every other plugin's: installing it does not give any bot the tools, and granting it to one bot says nothing about another. Revoking the grant, or turning the organisation's switch back off, takes the tools away from the next run — an existing grant is not a way around either value.

Which card number reaches whom

No tool returns a card number. What payments.request_spend answers is the card's last four digits, its expiry, the merchant it is locked to, its ceiling and the name the number is stored under — six facts and a name. The number itself is written where a password is already written, and is typed into a checkout page by the bot's computer rather than handed to the model.

Turning it on

There is nothing to do in another vendor's console. When this deployment has an issuer, an owner or administrator turns payments on for the organisation in Settings → Payments (/settings/payments), with its currency and caps, and the entry becomes installable; the member then installs it and grants it to the bots that should be able to ask. Until then the entry is visible and disabled, which is deliberate: an operator reading the marketplace should be able to see that the capability exists and what it is waiting for.

Link

Where the merchant's checkout offers Link, the member may pick one of their saved Link payment methods when approving. The bot still pays with the single-use card; once its one payment has gone through, the worker charges the chosen Link method for the amount the issuer approved. The operator's side of that is ../operations/bot-payments-runbook.md.