Withdrawals

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

State	What it means
`pending`	Request accepted, your USD balance debited in full, queued for processing. Not yet on-chain.
`completed`	Broadcast succeeded and confirmed on-chain. `txHash` is populated. Balance stays debited.
`reversed`	Broadcast was attempted but was unsuccessful. Balance refunded in full.
`rejected`	Failed 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).

Network	USDT	USDC
Ethereum (ERC20)	Yes	Yes
Tron (TRC20)	Yes	Yes
BNB Smart Chain (BSC)	Yes	Yes
Solana	Yes	Yes
TON	Yes	No

For testnet IDs and the full deposit/withdrawal asset catalog, see Supported assets.

Before you can withdraw

Requirement	Detail
Active credentials	Valid `x-app-id` / `x-app-secret`, integration in `active` state.
Funded USD wallet	Balance ≥ `amount + fee`. Both are debited together at request time.
PIN set	The `pin` field is required in the request body. Set or rotate it from the dashboard.
Account in good standing	Suspended or frozen accounts are blocked.
IP allowlist (optional)	If configured on your integration, the request must come from an allowed IP.

Happy path

You submit the request

Call POST /payments/withdraw/address:

{
  "amount": 100,
  "token": "USDT",
  "network": "TRC20",
  "walletAddress": "TRecipientTronAddressHere...",
  "pin": "1234",
  "externalId": "your-internal-id-123"
}

Field	Notes
`amount`	USD value, up to 2 decimal places. Subject to your integration’s min/max.
`token`	`USDT` or `USDC`.
`network`	`ERC20`, `TRC20`, `BSC`, `SOL`, or `TON` (TON supports USDT only).
`walletAddress`	Valid address for the network. Cannot be a Breet-managed address.
`pin`	Required even for server-to-server calls.
`externalId`	Optional. Your reference, useful for matching webhooks.

Breet responds synchronously with the withdrawal id.

Breet validates and debits

Synchronous checks, in order:

Credentials and integration active.
IP in allowlist (if configured).
PIN is correct. Repeated wrong PINs can temporarily freeze the account.
amount within min/max.
Address is valid for the network and not a Breet-managed address.
Not a duplicate request.
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.

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

Breet confirms completion

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

Webhook sequence, by scenario

Scenario	Events (same `id`)
Clean withdrawal	`withdrawal.pending` → `withdrawal.completed`
Blocked pre-broadcast	`withdrawal.pending` → `withdrawal.rejected` (refunded)
Broadcast failed	`withdrawal.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 deducted from the amount you request. Your balance is debited the full amount, and the recipient receives amount − fee on-chain. Example. You call with amount: 100, USDT on Tron, fee $1. Your balance is debited $100. The recipient receives $99 of USDT on Tron.

Fetching withdrawals via the API

Purpose	Endpoint
List withdrawals	`GET /payments/withdrawals`
Fetch one by ID	`GET /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

Can I withdraw BTC, ETH, SOL, or other native coins?

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.

Can I cancel a pending withdrawal?

Not via API. Contact support immediately after submitting if it’s critical. Once approved and broadcast, the withdrawal can only complete or reverse.

What if I send to the wrong address?

On-chain transactions are irreversible. Breet validates address format, not ownership. Always confirm the destination with your end-user before submitting.

How quickly do withdrawals complete?

Seconds/Minutes on Solana, Tron, and TON. Longer on EVM chains due to confirmation times.

Why do I need a PIN for an API call?

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

Set up webhook handling → Webhooks
See supported withdrawal networks and tokens → Supported assets
Handle 429s correctly → Rate limiting
Simulate a withdrawal on testnet → Testing

Getting started

Core concepts

Use cases

Withdrawal states

Withdrawal assets (mainnet)

Before you can withdraw

Happy path

Webhook sequence, by scenario

Fees and minimums

Fetching withdrawals via the API

FAQ

Next steps

​Withdrawal states

​Withdrawal assets (mainnet)

​Before you can withdraw

​Happy path

​Webhook sequence, by scenario

​Fees and minimums

​Fetching withdrawals via the API

​FAQ

​Next steps

Withdrawal states

Withdrawal assets (mainnet)

Before you can withdraw

Happy path

Webhook sequence, by scenario

Fees and minimums

Fetching withdrawals via the API

FAQ

Next steps