> ## 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.

# GET /payouts/history — View Your Payout History

> Retrieve your Tip Stack payout history: all fiat withdrawal requests with amounts, status, timestamps, and bank account details.

Use this endpoint to retrieve a full list of all withdrawal requests you have ever made from your Tip Stack account. Each record shows the NGN amount, the equivalent USDC value, the current processing status, and the reference you can use to follow up with support or Fossa Pay.

## Endpoint

```
GET https://tipstack.fun/api/payouts/history
```

## 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.

## Query Parameters

This endpoint does not accept any query parameters. All payout records for the authenticated creator are returned, ordered by `createdAt` descending (most recent first), up to the 50 most recent entries.

## Response

<ResponseField name="success" type="boolean">
  `true` when the request completed successfully.
</ResponseField>

<ResponseField name="history" type="array">
  An array of payout records. Sorted newest-first, capped at 50 entries.

  <Expandable title="Payout record fields">
    <ResponseField name="id" type="string | number">
      The internal database ID for this payout record.
    </ResponseField>

    <ResponseField name="reference" type="string">
      The unique payout reference (e.g. `FOSSA-1a2b3c4d5e6f7890`) generated when you called `/payouts/withdraw`. Use this to identify a specific withdrawal when contacting support.
    </ResponseField>

    <ResponseField name="amountUSDC" type="number">
      An approximate USD value back-calculated from `amountNGN`. Use this for display purposes only — it may not exactly match the USD amount originally withdrawn.
    </ResponseField>

    <ResponseField name="amountNGN" type="number">
      The gross NGN amount requested before any platform fee deductions.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the payout. See the table below for all possible values.
    </ResponseField>

    <ResponseField name="date" type="string">
      ISO 8601 datetime string indicating when the withdrawal was created.
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Values

| Status       | Meaning                                                                                |
| ------------ | -------------------------------------------------------------------------------------- |
| `pending`    | Recorded in the Tip Stack ledger; not yet sent to the payout provider.                 |
| `submitted`  | Accepted by Fossa Pay and queued for processing.                                       |
| `processing` | The bank transfer is actively in progress.                                             |
| `completed`  | Funds have been credited to your bank account.                                         |
| `failed`     | The payout was rejected or encountered an error. Contact support with the `reference`. |

## Example

### Request

```bash theme={null}
curl "https://tipstack.fun/api/payouts/history" \
  -b "session=YOUR_SESSION_COOKIE"
```

### Response

```json theme={null}
{
  "success": true,
  "history": [
    {
      "id": 42,
      "reference": "FOSSA-1a2b3c4d5e6f7890",
      "amountUSDC": 50.00,
      "amountNGN": 80000,
      "status": "completed",
      "date": "2024-06-15T09:30:00.000Z"
    },
    {
      "id": 37,
      "reference": "FOSSA-9z8y7x6w5v4u3210",
      "amountUSDC": 20.00,
      "amountNGN": 32000,
      "status": "failed",
      "date": "2024-06-10T14:15:22.000Z"
    },
    {
      "id": 31,
      "reference": "FOSSA-abcdef1234567890",
      "amountUSDC": 100.00,
      "amountNGN": 160000,
      "status": "completed",
      "date": "2024-05-28T11:02:45.000Z"
    }
  ]
}
```

<Info>
  The `amountUSDC` field is an approximation back-calculated from `amountNGN` using a fixed reference rate. It may differ from the exact USD amount you originally requested. For the precise withdrawal amount, refer to your original withdrawal request.
</Info>

## Error Responses

| Status             | Error                     | Cause                                                            |
| ------------------ | ------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized` | `"Unauthorized"`          | No active session cookie was found, or your session has expired. |
| `500 Server Error` | `"Internal Server Error"` | An unexpected error occurred on the server.                      |