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

# POST /payouts/withdraw — Withdraw Earnings to Bank

> Withdraw your Tip Stack USDC earnings to a Nigerian naira bank account via Fossa Pay. Requires authentication and a verified bank account.

Use this endpoint to initiate a fiat payout from your Tip Stack USDC balance directly to a Nigerian naira bank account. The platform converts your USDC earnings to NGN via the current exchange rate and routes the payout through Fossa Pay. You receive the converted amount minus the platform fee.

<Note>
  Fiat withdrawals are currently available to Nigerian bank accounts only. More regions coming soon.
</Note>

<Warning>
  Ensure your bank account details are correct before submitting. Failed withdrawals due to incorrect details may incur processing fees.
</Warning>

## Endpoint

```
POST https://tipstack.fun/api/payouts/withdraw
```

## Authentication

This endpoint requires an active creator session. You must be logged in — the API reads your identity from the session cookie set when you signed into your Tip Stack account. There is no Bearer token option for this endpoint.

## Request Body

<ParamField body="amountUSDC" type="number">
  The USDC amount to withdraw. Provide either `amountUSDC` **or** `amountNGN` — not both. Must be a positive number that does not exceed your available balance.
</ParamField>

<ParamField body="amountNGN" type="number">
  The NGN amount to withdraw, if you prefer to specify the target fiat amount directly. Provide either `amountNGN` **or** `amountUSDC` — not both.
</ParamField>

<ParamField body="bankCode" type="string" required>
  The Nigerian bank code for your destination account (e.g. `044` for Access Bank, `011` for First Bank). Supported bank codes are listed in your Tip Stack creator dashboard under **Payout Settings**.
</ParamField>

<ParamField body="accountNumber" type="string" required>
  Your 10-digit Nigerian bank account number. Numeric characters only — any non-digit characters are stripped automatically.
</ParamField>

<ParamField body="accountName" type="string" required>
  The account holder's name exactly as it appears on the bank account. This value is sent to Fossa Pay for verification; mismatches may cause the payout to be rejected.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the withdrawal was submitted successfully.
</ResponseField>

<ResponseField name="reference" type="string">
  A unique withdrawal reference ID in the format `FOSSA-<hex>`. Save this value to look up the payout status later.
</ResponseField>

<ResponseField name="status" type="string">
  The initial status of the withdrawal. Always `"pending"` or `"submitted"` on a successful response — see the lifecycle below.
</ResponseField>

<ResponseField name="amountNGN" type="number">
  The NGN amount that will be deposited into your bank account after the platform fee is deducted.
</ResponseField>

<ResponseField name="systemFeeNGN" type="number">
  The platform fee deducted from your withdrawal, denominated in NGN.
</ResponseField>

<ResponseField name="amountUSDC" type="number">
  The original USDC amount you requested. Only present when the withdrawal was denominated in USDC.
</ResponseField>

<ResponseField name="currency" type="string">
  The currency denomination of the withdrawal request — either `"USDC"` or `"NGN"`.
</ResponseField>

## Withdrawal Status Lifecycle

Each withdrawal moves through the following states:

| Status       | Meaning                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------- |
| `pending`    | The withdrawal has been recorded in our ledger but has not yet been sent to Fossa Pay.    |
| `submitted`  | The payout request has been accepted by Fossa Pay and is being processed.                 |
| `processing` | Fossa Pay has initiated the bank transfer.                                                |
| `completed`  | Funds have been credited to your bank account.                                            |
| `failed`     | The payout was rejected. Check the Fossa Pay dashboard or contact support for the reason. |

<Tip>
  Use [`GET /payouts/history`](/api/payouts/history) to poll the status of your withdrawal using the `reference` returned here.
</Tip>

## KYC Requirements

Withdrawals above certain thresholds may require you to complete identity verification before the payout is processed. If your account is flagged for KYC review, you will receive an email with instructions. Pending withdrawals are held until verification is complete.

## Example

### Request

```bash theme={null}
curl -X POST https://tipstack.fun/api/payouts/withdraw \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION_COOKIE" \
  -d '{
    "amountUSDC": 50.00,
    "bankCode": "044",
    "accountNumber": "0123456789",
    "accountName": "Ada Okonkwo"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "provider": "fossapay",
  "reference": "FOSSA-1a2b3c4d5e6f7890",
  "status": "submitted",
  "amountNGN": 78250,
  "systemFeeNGN": 1750,
  "currency": "USDC"
}
```

## Error Responses

| Status             | Error                     | Cause                                                                |
| ------------------ | ------------------------- | -------------------------------------------------------------------- |
| `400 Bad Request`  | `"Invalid amount"`        | `amountUSDC` or `amountNGN` is missing, zero, or negative.           |
| `400 Bad Request`  | `"Insufficient Balance"`  | The requested amount exceeds your available balance.                 |
| `400 Bad Request`  | `"Bank details required"` | `bankCode`, `accountNumber`, or `accountName` is missing or invalid. |
| `401 Unauthorized` | `"Unauthorized"`          | No active session cookie was found.                                  |
| `502 Bad Gateway`  | Fossa Pay error           | Fossa Pay rejected or failed to process the payout request.          |
| `500 Server Error` | `"Internal Server Error"` | An unexpected error occurred.                                        |