# Payouts

> Create, retrieve, update, cancel, and list payouts to your bank account.

A payout moves funds from your VINR balance to your connected bank account. VINR calculates the
available balance from captured payments minus fees, and you can trigger a payout manually or let
VINR schedule them automatically.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The payout object

- **id** `string` — Unique identifier for the payout, e.g. `po_7Kx3mBqR`.
- **amount** `integer` — Amount to be transferred to your bank account, in the smallest currency unit (e.g. cents).
- **currency** `string` — Three-letter ISO currency code, e.g. `EUR`.
- **status** `enum` — One of `pending`, `paid`, `failed`, or `canceled`.
- **arrival\_date** `timestamp` — Unix timestamp for the estimated date the payout will arrive in the bank account.
- **bank\_account** `object` — Snapshot of the destination bank account.
  - **last4** `string` — Last four digits of the account number.
  - **bank\_name** `string` — Name of the receiving bank, e.g. `Deutsche Bank`.
- **created** `timestamp` — Unix timestamp of when the payout was created.

## Create a payout

Specify an amount and currency to initiate an immediate transfer from your VINR balance to your bank
account. The payout starts in `pending` and transitions to `paid` once the bank confirms receipt.

`POST /v1/payouts`

```bash
curl -X POST https://api.vinr.com/v1/payouts \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d amount=100000 \
-d currency=EUR
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payout = await vinr.payouts.create({
amount: 100000,
currency: 'EUR',
});
```

```python
import vinr

payout = vinr.Payout.create(
  amount=100000,
  currency="EUR",
)
```

```ruby
payout = Vinr::Payout.create(
amount: 100000,
currency: 'EUR',
)
```

```json
{
"id": "po_7Kx3mBqR",
"amount": 100000,
"currency": "EUR",
"status": "pending",
"arrival_date": 1716556800,
"bank_account": {
  "last4": "4242",
  "bank_name": "Deutsche Bank"
},
"created": 1716300000
}
```

## Retrieve a payout

`GET /v1/payouts/{id}`

```bash
curl https://api.vinr.com/v1/payouts/po_7Kx3mBqR \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payout = await vinr.payouts.retrieve('po_7Kx3mBqR');
```

```python
import vinr

payout = vinr.Payout.retrieve("po_7Kx3mBqR")
```

```ruby
payout = Vinr::Payout.retrieve("po_7Kx3mBqR")
```

```json
{
"id": "po_7Kx3mBqR",
"amount": 100000,
"currency": "EUR",
"status": "paid",
"arrival_date": 1716556800,
"bank_account": {
  "last4": "4242",
  "bank_name": "Deutsche Bank"
},
"created": 1716300000
}
```

## Update a payout

Update mutable metadata on a payout. Only the `metadata` field can be changed after creation.

`POST /v1/payouts/{id}`

```bash
curl -X POST https://api.vinr.com/v1/payouts/po_7Kx3mBqR \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d "metadata[order_id]=ord_001"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payout = await vinr.payouts.update('po_7Kx3mBqR', {
metadata: { order_id: 'ord_001' },
});
```

```python
import vinr

payout = vinr.Payout.modify(
  "po_7Kx3mBqR",
  metadata={"order_id": "ord_001"},
)
```

```ruby
payout = Vinr::Payout.update(
"po_7Kx3mBqR",
metadata: { order_id: 'ord_001' },
)
```

```json
{
"id": "po_7Kx3mBqR",
"amount": 100000,
"currency": "EUR",
"status": "pending",
"arrival_date": 1716556800,
"bank_account": {
  "last4": "4242",
  "bank_name": "Deutsche Bank"
},
"metadata": {
  "order_id": "ord_001"
},
"created": 1716300000
}
```

## Cancel a payout

A payout can only be canceled while its status is `pending`. Once the bank has begun processing the
transfer, cancellation is no longer possible.

`POST /v1/payouts/{id}/cancel`

```bash
curl -X POST https://api.vinr.com/v1/payouts/po_7Kx3mBqR/cancel \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payout = await vinr.payouts.cancel('po_7Kx3mBqR');
```

```python
import vinr

payout = vinr.Payout.cancel("po_7Kx3mBqR")
```

```ruby
payout = Vinr::Payout.cancel("po_7Kx3mBqR")
```

```json
{
"id": "po_7Kx3mBqR",
"amount": 100000,
"currency": "EUR",
"status": "canceled",
"arrival_date": 1716556800,
"bank_account": {
  "last4": "4242",
  "bank_name": "Deutsche Bank"
},
"created": 1716300000
}
```

## List payouts

Returns a list of payouts, optionally filtered by status. Results are sorted by creation date,
newest first.

`GET /v1/payouts`

```bash
curl "https://api.vinr.com/v1/payouts?status=paid&limit=3" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payouts = await vinr.payouts.list({
status: 'paid',
limit: 3,
});
```

```python
import vinr

payouts = vinr.Payout.list(
  status="paid",
  limit=3,
)
```

```ruby
payouts = Vinr::Payout.list(
status: 'paid',
limit: 3,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "po_7Kx3mBqR",
    "amount": 100000,
    "currency": "EUR",
    "status": "paid",
    "arrival_date": 1716556800,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`payout.created`, `payout.paid`, `payout.failed`, and `payout.canceled`. See [Events](/docs/api-reference/events).