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 in destination, currency, and who bears the fee. 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`. The full `amount` is debited at request time and the `fee` comes out of it.
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.

All pass → amount 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 amount − fee on-chain (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.

Who bears the fee on bank withdrawals

Bank withdrawals carry a flat fee per payout, set per destination currency. Read the fee that currently applies to your integration from GET /users/fetch-integration as withdrawalFee:

"withdrawalFee": {
  "ngn": 50,
  "ghs": 1
}

You choose which side of the payout it comes out of with the withdrawalFeeBearer setting on your integration.

`withdrawalFeeBearer`	Debited from your balance	Recipient is credited	Use when
`user` (default)	`amount`	`amount − fee`	You pass the fee on to your end-user.
`business`	`amount + fee`	`amount`	You absorb the fee so your end-user is paid in full.

Example. A ₦50,000 payout with a ₦50 fee:

user — your balance is debited ₦50,000, the destination account is credited ₦49,950.
business — your balance is debited ₦50,050, the destination account is credited ₦50,000.

Breet charges the fee exactly once either way. The setting only decides who absorbs it, never how much it is.

This setting applies to bank withdrawals and to auto-settlement payouts, both of which pay out to an NGN or GHS bank account. Stablecoin withdrawals are unaffected — their network fee is always deducted from the amount, as described above.

Set the fee bearer

Set this from the Business tab on the Developer page in your dashboard. The new value applies to withdrawals created after you save it — a withdrawal already in pending keeps the pricing it was created with. The GET /users/fetch-integration response returns the current setting as withdrawalFeeBearer, and every bank withdrawal records the bearer that applied to it as meta.feeBearer, so you can reconcile a payout against the setting that was live when it was created.

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

Who bears the fee on bank withdrawals

Set the fee bearer

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

​Who bears the fee on bank withdrawals

​Set the fee bearer

​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

Who bears the fee on bank withdrawals

Set the fee bearer

Fetching withdrawals via the API

FAQ

Next steps