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

# Account and wallets

> Read your account, configure fees and hold expiry, and track the funds in each wallet.

Your **account** is the business or individual that sends payouts. It holds one or more **wallets**, each in a single currency, and every payout is paid from the wallet you choose when you create it.

## The account

```bash theme={null}
curl "$BASE/account" -H "Authorization: Bearer $INFINITY_KEY"
```

```json Response theme={null}
{
  "id": "account_5u9q6vhek42vemdc",
  "company_name": "Acme Ltd",
  "email": "ops@acme.com",
  "contact": { "first_name": "Jane", "last_name": "Doe", "phone": "+442071234567" },
  "registered_address": "1 High St, London",
  "status": "active",
  "settings": { "fee_bearer": "account", "hold_expiry_days": 30 },
  "created_at": "2026-09-01T09:00:00Z"
}
```

* `company_name` is `null` for an individual account; the person is identified by `contact`.
* `status` is `active` or `inactive`. API keys of an inactive account fail with `403 account_inactive`.
* Profile fields come from onboarding and aren't editable through the API. Contact your Infinity team to change them.

## Settings

Two settings change how new payouts behave.

| Setting | Values | Effect |
| - | - | - |
| `fee_bearer` | `account` (default), `payee` | Who pays Infinity's fee. With `account`, the fee is added to what the wallet is debited and the payee receives the full amount. With `payee`, the fee is deducted from what the payee receives. |
| `hold_expiry_days` | `30` (default), `60`, `90` | How long a payout to a payee who isn't ready can stay on hold before it expires and its funds are released. |

```bash theme={null}
curl "$BASE/account/settings" \
  -H "Authorization: Bearer $INFINITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fee_bearer": "payee" }'
```

The update is atomic: if any value is invalid, nothing changes and the response is `400 invalid_payer_setting_request`. A change applies to payouts created afterwards. Existing payouts keep the `fee_bearer` and `hold_expires_at` they were created with. See [Quotes and pricing](https://docs.infinityapp.in/guides/quotes-and-pricing.md) for how `fee_bearer` changes the amounts.

## Wallets

A wallet holds funds in one currency. You can hold wallets in several currencies, and each payout request names the wallet that pays for it with `wallet_id`.

```bash theme={null}
curl "$BASE/wallets" -H "Authorization: Bearer $INFINITY_KEY"
```

```json Response theme={null}
{
  "data": [
    { "id": "wallet_7t4m9k2qx8d3hn5r", "currency": "usd", "total": "5752.00", "reserved": "14.00", "available": "5738.00" },
    { "id": "wallet_2h9q6m3kx7t4dr8n", "currency": "eur", "total": "1200.00", "reserved": "0.00", "available": "1200.00" }
  ],
  "has_more": false
}
```

| Field | Meaning |
| - | - |
| `id` | The wallet's ID. Pass it as `wallet_id` when you quote or create payouts. |
| `currency` | The wallet's currency, lowercase ISO 4217. |
| `total` | All funds in the wallet, including reserved funds. |
| `reserved` | Funds set aside for payouts that are on hold or in flight. |
| `available` | `total` minus `reserved`: what new payouts can use. |

Amounts are read live on every request. `GET /wallets/{id}` returns a single wallet.

## How a wallet's amounts change

| Event | `total` | `reserved` | `available` |
| - | - | - | - |
| A deposit is credited | increases | | increases |
| Payouts are created, including payouts on hold | | increases by their `debit_amount` | decreases |
| A payout is sent to the network | decreases | decreases | |
| A payout on hold is canceled or expires | | decreases | increases |
| A payout fails | | decreases | increases |
| A paid payout is returned by the payee's bank | increases when the funds arrive back | | increases |

When you create payouts, Infinity checks the total `debit_amount` against the chosen wallet's `available` amount. If it doesn't fit, the request fails with `400 insufficient_funds` and nothing is created. A [quote](https://docs.infinityapp.in/guides/quotes-and-pricing.md) reports the same check as `sufficient_balance` without side effects.

> [!NOTE]
>
> For accounts enabled for payouts to India, a failed INR payout's funds are released after a review by our operations team rather than immediately.

## Events

| Event | What it means for a wallet |
| - | - |
| `deposit.created` | Funds were credited. |
| `payout.canceled`, `payout.expired` | A reservation was released. |
| `payout.failed` | A payout wasn't delivered; its funds are being released. |
| `payout.returned` | A paid payout came back from the payee's bank. |

See [Reconciliation](https://docs.infinityapp.in/guides/reconciliation.md) for matching these against your ledger.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.