Payments

A payment moves money from a visitor to the owner of a site.

Two directions of money exist here and they share nothing but a provider.

The owner is the merchant. Refunds, disputes, payouts and tax reports are theirs, in a tool that already exists.

The payout account

Money reaches an owner through a payout account. The owner makes a restricted key in their own Stripe dashboard and gives it to Clave, and Clave registers a webhook on their account with it.

Clave seals that key. No surface returns it, no log holds it, and only its last four characters are ever read back.

Clave asks Stripe for nothing on the owner's behalf. That is the point of this rail: no platform relationship, so nothing to approve.

A site pays into an account by agreement

A site pays into a payout account only when both sides agree, and the agreement is an offer.

• The site's owner names a payout account by its id, or the payout account's owner names a site by its public hostname.
• The other side accepts, for its own account and no other.

Clave sends no mail about an offer. GET /v1/payout-offers and the offers_to_answer count in the whoami are how an account learns of one.

One open offer for each site. Either party ends the agreement.

The pay link

GET /pay/{token} is a link Clave mints. Each time it is opened, Clave makes a fresh hosted page at the provider.

Nothing is remembered, because a remembered page is one that quietly died: a hosted page lives for hours and a hold can live longer.

What a payment knows

A payment knows money. It does not know what was bought. A reference field holds whatever is being paid for, as text Clave never reads inside.

Four rules worth knowing

• A hold is an expiry, not a status. A held payment past its expiry is expired.
• A late payment never revives a hold. The provider's reference is written first and unconditionally, so money that arrived too late is still refundable.
• A refund goes where the charge went. A site that changes payout account does not strand its old money.
• A new owner does not refund the old owner's money. A payment from before a site changed owner is refundable here only while its payout account still serves the site.
• The webhook is the only writer of money. A refund the owner makes in their own dashboard arrives through the same door.

A finished page is not money

A card pays while the payer is on the page. A bank debit finishes the page and pays days later. So Clave reads whether the charge is paid, on every delivery, rather than trust that a finished page means money arrived.

Test payments on drafts

A draft takes test money only. Each site has one draft account: a connected account in a test mode of the provider that is separate from the one the live site uses. All the drafts of the site pay into it.

• The owner sets it up on the draft view of the site's Payments page, or with the MCP tool set_up_draft_payments. Clave makes it with test data, and it is active at once, with no form. Until then, a payment on a draft answers 409 no_draft_account.
• It takes the country and currency of the live site's payout account. The owner can choose others (Australia, Spain, the United Kingdom or the United States), and Clave makes a new draft account.
• When the owner must test something in the provider's full dashboard, they use the provider's form instead (kind: hosted), and fill it in with its test data. It replaces the draft account, and the owner can go back. A payment made on an earlier draft account is refunded from it.
• A payment knows its slot: 0 for the live site, the draft's slot for a draft. A draft payment never reaches a live account, and a live payment never reaches the draft account.
• The payer comes back to the draft's address, and its events go to the draft only.
• The live site's totals and lists show live payments only. The draft view shows the draft's.
• A draft account is not a payout account in the lists, and a site cannot be pointed at it.

Read Payments.