Payments
Read Payments for the rails, the payout account and what a hold is.
GET /v1/account reports payouts. A deployment that cannot take money
for an owner says enabled: false and lists nothing.
The payout account
| Call | What it does |
|---|---|
POST /v1/account/payout-accounts |
adds one |
GET /v1/account/payout-accounts |
lists them, with what each waits for |
PATCH /v1/account/payout-accounts/{id} |
renames one |
POST /v1/account/payout-accounts/{id}/key |
replaces its secret key |
PUT /v1/account/payout-accounts/{id}/publishable-key |
sets its publishable key |
DELETE /v1/account/payout-accounts/{id} |
removes it |
GET /v1/account/payout-accounts/{id}/sites |
the sites it takes money for |
Send secret_key with a restricted key from the owner's own dashboard.
Clave seals it. No surface reads it back, and only its last four
characters are ever shown.
The card form on a site's own page also needs the publishable key of that
account, as publishable_key. It is public. It must have the mode of the
secret key. A new secret key of the other mode clears it. Without it, the
payer pays on the hosted page.
POST /v1/account/payout-accounts/{id}/onboarding is for the other rail,
where Clave asks the provider for a connection link. It refuses an account
that brought its own key.
The listing says what each account waits for. Read the listing rather than guess a cause: Clave cannot see inside somebody else's provider account, and an answer that guesses is an answer that blames the wrong party.
Point a site at one
| Call | What it does |
|---|---|
POST /v1/sites/{id}/payout-account |
attaches one of your own |
DELETE /v1/sites/{id}/payout-account |
ends the agreement |
DELETE is the one site call that does not start from the site's own
access check. The payout account's owner is not a collaborator on a site
they take the money for, and either party may end it.
When the two sides are different accounts
A site pays into another account only by agreement. Either side opens an offer and the other side accepts.
| Call | What it does |
|---|---|
POST /v1/sites/{id}/payout-offers |
the site's owner names a payout account |
POST /v1/account/payout-accounts/{id}/offers |
the payout owner names a site by hostname |
GET /v1/payout-offers |
offers waiting for your answer |
GET /v1/payout-offers/{id} |
one offer |
POST /v1/payout-offers/{id}/accept |
accepts, for your account and no other |
DELETE /v1/payout-offers/{id} |
takes it back |
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.
Take money
| Call | What it does |
|---|---|
POST /v1/sites/{id}/payments |
makes a payment and a pay link |
GET /v1/sites/{id}/payments |
the site's payments |
GET /v1/payments/{id} |
one payment |
POST /v1/payments/{id}/refund |
refunds it |
A payment takes an amount and a reference, which is text Clave never
reads inside. The currency is always the payout account's: a payment
cannot name one. Put an order id or an invoice number there.
Send the pay link to the payer. Each time the link is opened, Clave mints a fresh hosted page.
A refund goes where the charge went. If the payout account is gone, Clave says so and says the money is not lost: it is refundable in the owner's own dashboard.
A payment from before the site changed owner is refundable here only
while its payout account serves the site, or belongs to the new owner.
Otherwise the answer is 403 refund_needs_payout_owner, and the old owner
refunds it in their own dashboard. Read
Give a site to another account.