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

# Balance and withdrawals

> Everything you collect lands in your Flipeet balance. From there, pay out to a wallet or to a bank account.

## Check your balance

```bash cURL theme={null}
curl "https://api.pay.flipeet.io/api/v1/merchant/balance" \
  -H "x-api-key: $FLIPEET_SECRET_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pay.flipeet.io/api/v1/merchant/balance", {
  method: "GET",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
  },
});
const { data } = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.get(
    "https://api.pay.flipeet.io/api/v1/merchant/balance",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
)
data = response.json()["data"]
```

```json Response theme={null}
{
  "message": "Balance retrieved",
  "status": "success",
  "statusCode": 200,
  "data": {
    "livemode": true,
    "balances": [
      { "currency": "usdc", "available": 1240.5 },
      { "currency": "usdt", "available": 310 }
    ]
  }
}
```

## Withdraw to a wallet

Send USDC or USDT to any address on a supported network. The amount leaves your balance straight away, and the withdrawal is `processing` until the network confirms it.

```bash cURL theme={null}
curl -X POST "https://api.pay.flipeet.io/api/v1/merchant/transaction/crypto/withdrawal" \
  -H "x-api-key: $FLIPEET_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 250,
  "network": "base",
  "asset": "usdc",
  "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
  "reference": "payout_5510"
}'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pay.flipeet.io/api/v1/merchant/transaction/crypto/withdrawal", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": 250,
    "network": "base",
    "asset": "usdc",
    "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    "reference": "payout_5510"
  }),
});
const { data } = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.pay.flipeet.io/api/v1/merchant/transaction/crypto/withdrawal",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
    json={
        "amount": 250,
        "network": "base",
        "asset": "usdc",
        "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
        "reference": "payout_5510"
    },
)
data = response.json()["data"]
```

> [!WARNING]
>
> On-chain transfers can't be reversed. Check the address and network before you send; a transfer on the wrong network may be lost.

## Withdraw to a bank

Pay local currency to a bank account from your stablecoin balance. Get the bank's `bank_code` from [List institutions](https://docs.flipeet.io/api-reference/ramps/list-institutions.md), and confirm the account holder's name with [Verify an account](https://docs.flipeet.io/api-reference/ramps/verify-an-account.md) before you pay.

```bash cURL theme={null}
curl -X POST "https://api.pay.flipeet.io/api/v1/merchant/transaction/fiat/withdrawal" \
  -H "x-api-key: $FLIPEET_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "currency": "usdc",
  "payoutCurrency": "NGN",
  "country": "NG",
  "beneficiary": {
    "holder_name": "Chidi Okafor",
    "holder_type": "individual",
    "account_number": "0123456789",
    "bank_code": "044"
  },
  "reference": "payout_5511"
}'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.pay.flipeet.io/api/v1/merchant/transaction/fiat/withdrawal", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": 100,
    "currency": "usdc",
    "payoutCurrency": "NGN",
    "country": "NG",
    "beneficiary": {
      "holder_name": "Chidi Okafor",
      "holder_type": "individual",
      "account_number": "0123456789",
      "bank_code": "044"
    },
    "reference": "payout_5511"
  }),
});
const { data } = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.pay.flipeet.io/api/v1/merchant/transaction/fiat/withdrawal",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
    json={
        "amount": 100,
        "currency": "usdc",
        "payoutCurrency": "NGN",
        "country": "NG",
        "beneficiary": {
            "holder_name": "Chidi Okafor",
            "holder_type": "individual",
            "account_number": "0123456789",
            "bank_code": "044"
        },
        "reference": "payout_5511"
    },
)
data = response.json()["data"]
```

## Know when it's done

| Status | Means |
| - | - |
| `processing` | Sent to the network or the bank, and not confirmed yet. |
| `completed` | Delivered. For wallets, `txHash` is the on-chain transaction. |
| `failed` | Not delivered. The amount is back in your balance, and `failureReason` says why. |

You get `transaction.withdrawal.completed` or `transaction.withdrawal.failed`:

```json transaction.withdrawal.completed theme={null}
{
  "event": "transaction.withdrawal.completed",
  "type": "crypto",
  "reference": "payout_5510",
  "status": "completed",
  "currency": "usdc",
  "amount": 250,
  "network": "base",
  "asset": "usdc",
  "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
  "txHash": "0x65ecb80124d0d6802a0be19b8ea09b8d6e11d4af8d2eb8bff43feac9827b72a7",
  "note": null,
  "metadata": null,
  "livemode": true
}
```

> [!NOTE]
>
> Reusing a reference returns `409` without sending anything, so it's safe to retry a withdrawal that timed out with the same reference.

If a network or bank doesn't confirm a payout either way, it stays `processing` while we check it with them. We never refund a payout that may have gone through, and we never send it twice.


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