POST /payouts/withdraw — Withdraw Earnings to Bank

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.

Fiat withdrawals are currently available to Nigerian bank accounts only. More regions coming soon.

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

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

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.

number

The NGN amount to withdraw, if you prefer to specify the target fiat amount directly. Provide either amountNGN or amountUSDC — not both.

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.

string

required

Your 10-digit Nigerian bank account number. Numeric characters only — any non-digit characters are stripped automatically.

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.

Response

boolean

true when the withdrawal was submitted successfully.

string

A unique withdrawal reference ID in the format FOSSA-<hex>. Save this value to look up the payout status later.

string

The initial status of the withdrawal. Always "pending" or "submitted" on a successful response — see the lifecycle below.

number

The NGN amount that will be deposited into your bank account after the platform fee is deducted.

number

The platform fee deducted from your withdrawal, denominated in NGN.

number

The original USDC amount you requested. Only present when the withdrawal was denominated in USDC.

string

The currency denomination of the withdrawal request — either "USDC" or "NGN".

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.

Use GET /payouts/history to poll the status of your withdrawal using the reference returned here.

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

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

{
  "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.

Overview

Payments

Tips

SDK

Payouts

POST /payouts/withdraw — Withdraw Earnings to Bank

Endpoint

Authentication

Request Body

Response

Withdrawal Status Lifecycle

KYC Requirements

Example

Request

Response

Error Responses

​Endpoint

​Authentication

​Request Body

​Response

​Withdrawal Status Lifecycle

​KYC Requirements

​Example

​Request

​Response

​Error Responses

Endpoint

Authentication

Request Body

Response

Withdrawal Status Lifecycle

KYC Requirements

Example

Request

Response

Error Responses