# Payouts

Every paid charge has one payout: what came in, what was kept, what you are owed, what actually landed and the transaction that carried it. These endpoints only read: payouts go out on their own, and nothing here can raise, redirect or reverse one.

## The payout object

| Field | Type | Description |
| --- | --- | --- |
| `id, charge` | string | The id of the charge the payout came from. A charge has one payout, written when it is paid. |
| `object` | "payout" | The kind of object. |
| `status` | "pending" \| "sending" \| "sent" \| "failed" \| "manual" | Where it has got to. Pending waits for the next run or attempt, sending is broadcast and confirming, sent has confirmed, failed ran out of attempts and manual waits on an address or a person. |
| `asset` | string | The coin it was paid in and goes out in. |
| `gross_amount` | string | What the customer paid, in the coin. |
| `fee_percent, fee_amount` | string | The rate of the platform's fee and what was kept, in the coin. |
| `fee_fiat_amount, fiat_currency, exchange_rate` | string\|null | What the fee was worth in your currency, at the rate the charge was locked at. |
| `net_amount` | string | What you are owed, before the chain's own fee. |
| `network_fee, sent_amount` | string\|null | What the chain charged and what therefore reached you, once it has been broadcast. |
| `payout_address` | string\|null | Where it goes, as you had it configured when the charge was paid. Null while it waits for an address. |
| `payout_txid, explorer_url` | string\|null | The transaction that carried it, and its page on a block explorer. |
| `attempts, last_error` | integer, string\|null | How many times forwarding has been tried, and why the last try did not work or why it is held. |
| `next_attempt_at` | string\|null | When it may go out next, such as when a newly saved address has finished waiting. |
| `sent_at, confirmed_at, created_at` | string\|null | When it was broadcast, when it confirmed and when the books were written, as ISO 8601 timestamps in UTC. |

## Endpoints

- GET `/v1/payouts` List payouts, newest first. Filter with ?status=, ?asset= and ?search= (a charge id or a transaction hash).
- GET `/v1/payouts/summary` Add up, per coin, what has been paid out, what is on its way and what is still owed. In the mode of the key, and not paged.
- GET `/v1/payouts/{id}` Retrieve the payout of a charge, by the charge's id. Answers 404 until the charge is paid.

## Example: read a payout

```bash
curl https://api.velirapay.com/v1/payouts/2t4bcuqkpkoy \
  -H "Authorization: Bearer vp_live_…"
```

**Response**

```json
{
  "data": {
    "id": "2t4bcuqkpkoy",
    "object": "payout",
    "charge": "2t4bcuqkpkoy",
    "status": "sent",
    "asset": "USDT",
    "gross_amount": "11.014175",
    "fee_percent": "3",
    "fee_amount": "0.330425",
    "net_amount": "10.68375",
    "network_fee": "0.081611",
    "sent_amount": "10.602139",
    "payout_address": "0x7099…79C8",
    "payout_txid": "0x9a4f…c21e",
    "explorer_url": "https://etherscan.io/tx/0x9a4f…c21e",
    "confirmed_at": "2026-11-02T21:00:04.000000Z",
    …
  }
}
```

## The summary

GET /v1/payouts/summary answers with one row per coin the account has been paid in, and meta.mode:

| Field | Type | Description |
| --- | --- | --- |
| `asset` | string | The coin this row adds up. |
| `payouts` | integer | How many paid charges it covers. |
| `gross_amount, fee_amount` | string | What came in, and what was kept in fees. |
| `paid_out_amount` | string | What has reached you. |
| `in_flight_amount` | string | What is on its way and waiting to confirm. |
| `owed_amount` | string | What is still owed to you and has not left yet. |
| `network_fee_amount` | string | What the chains charged to forward it. |
| `waiting_for_address` | integer | How many payouts wait for you to give an address for this coin. |

[Read how a payment becomes a payout, who pays the network and which payouts wait →](https://velirapay.com/docs/settlement)