# Payouts

> Pay Fina Pay users from your own wallet: withdrawals, prizes, refunds outside a charge. Idempotent and instant.

A payout moves money from the Fina Pay wallet of the **connection owner** to another Fina user, in one atomic step. Fina does not create money: if your wallet does not have the balance, the payout is rejected. Use it to pay your users' withdrawals, prizes or anything you owe them.

> **Warning:** Payouts are **off by default**. The business owner turns on **Payouts via API** in the Fina Pay connector (business → Connectors → Fina Pay). While it is on, anyone with the secret key can send money from that wallet: keep the key on your server only.

### Flow

1. Your user enters their Fina Pay account number (10 digits) or the phone linked to their wallet.
2. Call `GET /recipients?account=…` and show them the `name` the money will go to, so they can confirm it is them.
3. Call `POST /payouts` with your withdrawal id as `reference`. A `201` means the money is already in their wallet; they get a notification.
4. Store the payout `id`. `GET /payouts/{id}` returns it again at any time.

**GET /recipients — curl**

```bash
curl "https://fina.do/api/wallet/v1/recipients?account=8095551234" \
  -H "Authorization: Bearer $FINA_SECRET_KEY"
```

**GET /recipients — Response**

```json
{
  "name": "María Pérez",
  "account": "2345678901"
}
```

**POST /payouts — curl**

```bash
curl -X POST https://fina.do/api/wallet/v1/payouts \
  -H "Authorization: Bearer $FINA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "2345678901",
    "amount_minor": 250000,
    "reference": "withdrawal-981",
    "description": "Retiro de tu saldo"
  }'
```

**POST /payouts — Response**

```json
{
  "id": "0b6f8f6e-2f4c-4a63-9d1e-3c1b2a7d9e10",
  "status": "completed",
  "amount_minor": 250000,
  "currency_code": "DOP",
  "reference": "withdrawal-981",
  "recipient": { "name": "María Pérez" },
  "created_at": "2026-10-08T15:04:05.000Z",
  "duplicate": false
}
```

| Field | Rules |
| --- | --- |
| `account` | Required. Account number or phone, the same values a Fina user can send money to. |
| `amount_minor` | Required. Integer > 0 in centavos. Debited from your wallet as is: there is no payout fee. |
| `reference` | Required, up to 64 characters, unique per connection. |
| `description` | Optional, up to 140 characters. The recipient sees it. |
| `metadata` | Optional JSON object (up to 4 KB), stored with the payout. |

### Idempotency

`reference` is unique per connection. Sending `POST /payouts` again with a reference that was already paid answers `200` with the original payout and `duplicate: true` — even if the body differs and even with simultaneous requests. Nothing is paid twice, so retry freely on timeouts with the same reference.

### Errors

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_json`, `invalid_amount`, `reference_required`, `invalid_reference`, `invalid_description`, `invalid_metadata` | Fix the request. |
| 400 | `same_account` | The recipient is the wallet of the connection owner. |
| 403 | `payouts_disabled` | Payouts via API are off for this connection. |
| 404 | `recipient_not_found` | No active Fina Pay wallet with that account number or phone. |
| 409 | `insufficient_funds` | Your wallet balance is lower than `amount_minor`. Nothing moved. |
| 409 | `currency_mismatch` | Your wallet and the recipient's use different currencies. |
| 409 | `wallet_blocked` | Your wallet is blocked. Contact Fina support. |

Full request and response schemas: [Fina Pay API reference](https://fina.do/developers/api-fina-pay.md).

Source: https://fina.do/developers#payouts