Skip to main content
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

​
amountUSDC
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.
​
amountNGN
number
The NGN amount to withdraw, if you prefer to specify the target fiat amount directly. Provide either amountNGN or amountUSDC — not both.
​
bankCode
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.
​
accountNumber
string
required
Your 10-digit Nigerian bank account number. Numeric characters only — any non-digit characters are stripped automatically.
​
accountName
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

​
success
boolean
true when the withdrawal was submitted successfully.
​
reference
string
A unique withdrawal reference ID in the format FOSSA-<hex>. Save this value to look up the payout status later.
​
status
string
The initial status of the withdrawal. Always "pending" or "submitted" on a successful response — see the lifecycle below.
​
amountNGN
number
The NGN amount that will be deposited into your bank account after the platform fee is deducted.
​
systemFeeNGN
number
The platform fee deducted from your withdrawal, denominated in NGN.
​
amountUSDC
number
The original USDC amount you requested. Only present when the withdrawal was denominated in USDC.
​
currency
string
The currency denomination of the withdrawal request — either "USDC" or "NGN".

​
Withdrawal Status Lifecycle

Each withdrawal moves through the following states:
StatusMeaning
pendingThe withdrawal has been recorded in our ledger but has not yet been sent to Fossa Pay.
submittedThe payout request has been accepted by Fossa Pay and is being processed.
processingFossa Pay has initiated the bank transfer.
completedFunds have been credited to your bank account.
failedThe 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

StatusErrorCause
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 GatewayFossa Pay errorFossa Pay rejected or failed to process the payout request.
500 Server Error"Internal Server Error"An unexpected error occurred.