Skip to main content
A withdrawal moves funds out of your Breet wallet. The Partners API supports two types:
  • Stablecoin withdrawals to an external wallet address — POST /payments/withdraw/address. USDT and USDC on Ethereum, Tron, BSC, Solana, and TON (TON is USDT-only). Debited from your USD balance.
  • Bank withdrawals to an NGN or GHS bank account — POST /payments/withdraw/bank/{id}. Debited from your local-currency balance.
Both types share the same lifecycle and webhook events. This page focuses on stablecoin withdrawals; bank withdrawals differ only in destination and currency. For automatic bank payouts tied to deposits, see Auto-settlement.

​
Withdrawal states

StateWhat it means
pendingRequest accepted, your USD balance debited in full, queued for processing. Not yet on-chain.
completedBroadcast succeeded and confirmed on-chain. txHash is populated. Balance stays debited.
reversedBroadcast was attempted but was unsuccessful. Balance refunded in full.
rejectedFailed an internal check before broadcast. Not sent on-chain. Balance refunded in full.
Each state change fires a webhook: withdrawal.pending, withdrawal.completed, withdrawal.reversed, or withdrawal.rejected.
Rejected ≠ reversed. Both refund your balance, but rejected means Breet blocked the withdrawal before it touched the blockchain; reversed means the transaction came back with a failure after an attempt to broadcast it. Only withdrawal.completed means the funds are on-chain at the destination.

​
Withdrawal assets (mainnet)

Withdrawals to external crypto addresses only support stablecoins (USDT and USDC).
NetworkUSDTUSDC
Ethereum (ERC20)YesYes
Tron (TRC20)YesYes
BNB Smart Chain (BSC)YesYes
SolanaYesYes
TONYesNo
For testnet IDs and the full deposit/withdrawal asset catalog, see Supported assets.

​
Before you can withdraw

RequirementDetail
Active credentialsValid x-app-id / x-app-secret, integration in active state.
Funded USD walletBalance ≥ amount + fee. Both are debited together at request time.
PIN setThe pin field is required in the request body. Set or rotate it from the dashboard.
Account in good standingSuspended or frozen accounts are blocked.
IP allowlist (optional)If configured on your integration, the request must come from an allowed IP.

​
Happy path

1

You submit the request

Call POST /payments/withdraw/address:
{
  "amount": 100,
  "token": "USDT",
  "network": "TRC20",
  "walletAddress": "TRecipientTronAddressHere...",
  "pin": "1234",
  "externalId": "your-internal-id-123"
}
FieldNotes
amountUSD value, up to 2 decimal places. Subject to your integration’s min/max.
tokenUSDT or USDC.
networkERC20, TRC20, BSC, SOL, or TON (TON supports USDT only).
walletAddressValid address for the network. Cannot be a Breet-managed address.
pinRequired even for server-to-server calls.
externalIdOptional. Your reference, useful for matching webhooks.
Breet responds synchronously with the withdrawal id.
2

Breet validates and debits

Synchronous checks, in order:
  1. Credentials and integration active.
  2. IP in allowlist (if configured).
  3. PIN is correct. Repeated wrong PINs can temporarily freeze the account.
  4. amount within min/max.
  5. Address is valid for the network and not a Breet-managed address.
  6. Not a duplicate request (see Idempotency below).
  7. Balance ≥ amount + fee.
All pass → amount + fee is debited, withdrawal is created with status: pending, withdrawal.pending webhook is queued.Any fail → no record, no debit, no webhook. You receive an HTTP error. See Error handling.
3

Breet approves and broadcasts

Approval is mostly automatic. The transaction is signed and broadcast on the chosen network. The recipient receives the full amount on-chain — the fee is charged separately (see Fees).Withdrawals flagged for internal review may stay in pending until Breet approves (typically within a few minutes).
4

Breet confirms completion

Once the withdrawal is successful, withdrawal.completed fires with the on-chain txHash.

​
Webhook sequence, by scenario

ScenarioEvents (same id)
Clean withdrawalwithdrawal.pending → withdrawal.completed
Blocked pre-broadcastwithdrawal.pending → withdrawal.rejected (refunded)
Broadcast failedwithdrawal.pending → withdrawal.reversed (refunded)
Webhook delivery is asynchronous and ordering isn’t guaranteed under variable endpoint latency. Trust the event and status fields on each payload, not the order they arrive in.

​
Fees and minimums

Breet charges a small flat fee per crypto to cover the network fee. The fee is shown on the webhook payload as fee. The fee is charged on top of the amount you request. Your balance must cover both, and both are debited at request time. The recipient receives the full amount on-chain. Example. You call with amount: 100, USDT on Tron, fee $1. Your balance is debited $101 (amount + fee). The recipient receives the full $100 of USDT on Tron.

​
Fetching withdrawals via the API

PurposeEndpoint
List withdrawalsGET /payments/withdrawals
Fetch one by IDGET /payments/withdrawal/{id}
On every webhook, fetch the withdrawal by id before updating your system of record. Combined with IP and secret verification, this is defence in depth.

​
FAQ

No. The Partners API supports only stablecoin withdrawals (USDT, USDC) on the networks listed above. To move native coins, sell them via a deposit first, then withdraw as a stablecoin.
Not via API. Contact support immediately after submitting if it’s critical. Once approved and broadcast, the withdrawal can only complete or reverse.
On-chain transactions are irreversible. Breet validates address format, not ownership. Always confirm the destination with your end-user before submitting.
Seconds/Minutes on Solana, Tron, and TON. Longer on EVM chains due to confirmation times.
It’s an additional verification layer in case your API keys leak. Store the PIN alongside your secrets and rotate it from the dashboard if exposed.

​
Next steps