# API: Payments

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/payments` | Payments on calls: whether the Stripe key and webhook secret are set, the webhook URL, the settings (on/off, approval threshold, maximum, link expiry), deposit rules and recent payment requests | `settings:read` |
| PUT | `/v1/payments` | Change the payment settings (owner). The key is the secret stripe_payments_key (a restricted key: Checkout Sessions write); the webhook's signing secret is stripe_webhook_secret | `integrations:write` |
| POST | `/v1/payments/deposit-rules` | Add a deposit rule (owner): a fixed amount or a percent of a catalog product's price, for a product or a named service. The voice agent can only charge what a rule says | `settings:write` |
| DELETE | `/v1/payments/deposit-rules/:id` | Turn a deposit rule off (owner) | `settings:write` |
| PUT | `/v1/payments/deposit-rules/:id` | Change a deposit rule (owner): saved as a new version | `settings:write` |
| POST | `/v1/payments/stripe/webhook/:id` | Stripe webhooks (public; Stripe-Signature HMAC-SHA256 over {t}.{raw body}, 5-minute tolerance; each event applied once). checkout.session.completed marks the payment paid and texts the confirmation (no sign-in) | — |

## Examples

### GET /v1/payments

Payments on calls: whether the Stripe key and webhook secret are set, the webhook URL, the settings (on/off, approval threshold, maximum, link expiry), deposit rules and recent payment requests

```bash
curl -s "https://api.closefinch.com/v1/payments" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/payments`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/payments

Change the payment settings (owner). The key is the secret stripe_payments_key (a restricted key: Checkout Sessions write); the webhook's signing secret is stripe_webhook_secret

```bash
curl -s -X PUT "https://api.closefinch.com/v1/payments" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/payments`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/payments/deposit-rules

Add a deposit rule (owner): a fixed amount or a percent of a catalog product's price, for a product or a named service. The voice agent can only charge what a rule says

```bash
curl -s -X POST "https://api.closefinch.com/v1/payments/deposit-rules" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/payments/deposit-rules`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### DELETE /v1/payments/deposit-rules/$ID

Turn a deposit rule off (owner)

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/payments/deposit-rules/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/payments/deposit-rules/${id}`, {
  method: "DELETE",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/payments/deposit-rules/$ID

Change a deposit rule (owner): saved as a new version

```bash
curl -s -X PUT "https://api.closefinch.com/v1/payments/deposit-rules/$ID" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/payments/deposit-rules/${id}`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).