> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onconsul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> Send USDC payouts to recipients via email

Once your Consul balance is funded, you can send payouts to one or more recipients in a single
API call. Payouts are on-chain USDC transfers on Base that settle in seconds.

### How Payouts Work

Each payout is a batch of items. Each item specifies an amount and a target - either an
**email address** or a **recipient ID**. Consul handles the rest:

* **Existing users** receive USDC directly in their Consul wallet.
* **New users** receive an email invite to claim their funds. Consul creates a wallet behind the
  scenes and guides them through onboarding.

<Info>
  Payouts are **atomic**. If any item in a batch fails validation (e.g. insufficient balance for
  the total), the entire payout is rejected. No partial transfers occur.
</Info>

### Sending a Payout

Use the [Create a Payout](/api-reference/payouts/create-a-payout) endpoint. You can target
recipients by email or by `recipient_id` if they've already been created via the
[Recipients API](/api-reference/recipients/create-a-recipient):

```bash theme={"system"}
curl -X POST https://api.onconsul.com/v1/payouts \
  -H "Authorization: Basic base64($CONSUL_API_KEY)" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"amount": "500", "email": "alice@example.com"},
      {"amount": "250", "recipient_id": "recipient_abc123"},
      {"amount": "1000", "email": "new-contractor@example.com"}
    ]
  }'
```

The response returns a payout in `processing` status. Individual items settle almost instantly
(\< 3s p99). Listen for the `transfer.updated` webhook to confirm each item has completed.

### Idempotency

Include an `Idempotency-Key` header to safely retry payout requests without creating
duplicates. If a request with the same key has already been processed, Consul returns the
original response.

### Payout Lifecycle

Each payout item follows its own lifecycle:

| Status          | Description                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `processing`    | Transfer initiated on-chain                                                    |
| `completed`     | USDC delivered to recipient's wallet                                           |
| `pending_claim` | Recipient isn't on the platform yet - funds are held securely until they claim |
| `cancelled`     | Payout was cancelled; funds returned to your balance                           |
| `expired`       | Payout expired; funds returned to your balance                                 |
| `failed`        | Transfer failed; a failure reason is provided                                  |

<Accordion title="Payout Item Lifecycle Diagram">
  ```mermaid theme={"system"}
  stateDiagram-v2
  [*] --> processing: Payout created
  processing --> completed: Recipient on platform
  processing --> pending_claim: Recipient not on platform
  processing --> failed: Error
  pending_claim --> completed: Recipient claims
  pending_claim --> cancelled: Cancelled
  pending_claim --> expired: Expired
  ```
</Accordion>

### Cancelling a Payout

You can cancel a payout that hasn't settled yet by calling
[POST /payouts/{id}/cancel](/api-reference/payouts/cancel-a-payout). This is only possible while the
payout is still in `processing` or `pending_claim` status. Once a payout item has `completed`, it cannot
be reversed.

```bash theme={"system"}
curl -X POST https://api.onconsul.com/v1/payouts/payout_abc123/cancel \
  -u $CONSUL_API_KEY
```

The response returns the updated payout object with a `cancelled` status. Funds are returned to your
Consul balance.

### Tracking Payouts

* **Get a Payout**: [GET /payouts/{id}](/api-reference/payouts/get-a-payout) returns the
  overall status, total amount, and item count.
* **List Payout Items**: [GET /payouts/{id}/items](/api-reference/payouts/list-payout-items)
  returns each item's recipient, amount, and status.