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.
| From | To | Merchant | |
|---|---|---|---|
| billing | an account | Clave | Clave |
| payments | a visitor | the site's owner | the owner |
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.
- 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.
Read Payments.