# Payouts

Onboard for payouts, check your balance, and move money out to your bank
account. Onboarding runs through Stripe Connect; everything you see here is in
your settlement currency (fiat).

Scopes: balance and payout reads accept either `payouts:read` or
`payouts:claim`; claiming a payout and both Connect onboarding endpoints
(including the status read) need `payouts:claim`.

---

## POST /v1/connect/account

Begin or resume payout onboarding. Creates a connected account on first call and
returns a fresh onboarding link to redirect your user to.

**Scope:** `payouts:claim`

This endpoint takes no request body.

### Example request

```bash
curl https://api.ticketconnect.example/v1/connect/account \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -X POST
```

### Example response

```json
{
  "account_id": "acct_1NxYz...",
  "onboarding_url": "https://connect.stripe.com/setup/e/acct_1NxYz.../abc123"
}
```

> Errors: `502 api_error` if the onboarding link cannot be created.

---

## GET /v1/connect/account

Retrieve your onboarding status — whether you can receive payouts yet. Returns
only capability booleans, never any personal information.

**Scope:** `payouts:claim`

### Example request

```bash
curl https://api.ticketconnect.example/v1/connect/account \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "connected": true,
  "charges_enabled": true,
  "payouts_enabled": true,
  "details_submitted": true
}
```

Before onboarding has started:

```json
{ "connected": false }
```

---

## GET /v1/balance

Retrieve your single spendable balance in your settlement currency.

**Scope:** `payouts:read` (or `payouts:claim`)

### Example request

```bash
curl https://api.ticketconnect.example/v1/balance \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "object": "balance",
  "available": 12840.50,
  "currency": "USD"
}
```

---

## GET /v1/payouts

List payouts made to your bank account, newest first.

**Scope:** `payouts:read` (or `payouts:claim`)

### Query params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size, `1`–`100` (default `20`). |
| `starting_after` | string | No | Cursor — a payout id to page after. |

### Example request

```bash
curl "https://api.ticketconnect.example/v1/payouts?limit=2" \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "6651aa...",
      "amount": 5000.00,
      "currency": "USD",
      "reference": "tr_1NxYz...",
      "created_at": "2026-06-04T08:00:00.000Z"
    }
  ]
}
```

---

## POST /v1/payouts

Request a payout of your available balance to your connected bank account. If
you omit `amount`, the full available balance is paid out. The amount can never
exceed your balance.

**Scope:** `payouts:claim`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | No | Amount to pay out. Defaults to the full available balance. Must be `> 0`. |
| `currency` | string | No | Currency; defaults to your settlement currency. |

Accepts an `Idempotency-Key` header.

### Example request

```bash
curl https://api.ticketconnect.example/v1/payouts \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-001" \
  -d '{ "amount": 5000.00 }'
```

### Example response

```json
{
  "object": "payout",
  "id": "tr_1NxYz...",
  "amount": 5000.00,
  "currency": "USD",
  "status": "paid"
}
```

> Errors: `400 parameter_invalid` (non-positive amount), `400 insufficient_balance`,
> `400 connect_account_required` (onboarding not complete), `502 api_error`.
> Emits a `payout.paid` webhook.