# Payments

Read [Payments](/concepts/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 |
| `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.

`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, a currency and a `reference`, which is text
Clave never reads inside. Put a booking 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.

---

## Where this page sits

This is one page of the Clave documentation.
Read it as a web page at https://docs.heyclave.party/api/payments.
Every page has a `.md` address, and https://docs.heyclave.party/llms.txt lists them all.

- Previous: [Bookings](https://docs.heyclave.party/api/bookings.md)
- Next: [Collaborators](https://docs.heyclave.party/api/collaborators.md)
- Index: [Overview](https://docs.heyclave.party/index.md)