Withdrawal callbacks

Body

application/json

integer

required

Withdrawal ID.

foreign_id

string

required

The foreign_id you provided when creating the withdrawal via the API.

For withdrawals initiated in the portal, where no foreign_id is provided, the field contains the time the withdrawal was created:

for single withdrawals, the Unix time in milliseconds — for example, "1790694052541"
for individual withdrawals from a mass payout, the fraction of the second and the Unix time in seconds, separated by a space — for example, "0.42905800 1790595801"

type

enum<string>

required

Withdrawal type:

withdrawal: standard withdrawal
withdrawal_exchange: standard withdrawal with conversion
withdrawal_instant: instant withdrawal
withdrawal_instant_exchange: instant withdrawal with conversion

Available options:

withdrawal,

withdrawal_exchange,

withdrawal_instant,

withdrawal_instant_exchange

crypto_address

object

required

Details of the address the funds are withdrawn to.

Hide child attributes

crypto_address.id

integer

required

Address ID.

crypto_address.currency

string

required

Code of the withdrawn currency. See API currency codes.

crypto_address.address

string

required

Destination address.

crypto_address.tag

string | null

required

Destination tag/memo. null if the withdrawal has none, for example for a currency that doesn't use tags.

transactions

(blockchain · object | internal · object | exchange · object)[]

required

Transactions related to the withdrawal. Every withdrawal has one blockchain or internal entry, and withdrawals with conversion have an additional exchange entry. The transaction_type field shows what each entry is:

blockchain: the outgoing transaction on the blockchain
internal: the outgoing transaction for an off-chain withdrawal, which is never sent to the blockchain
exchange: the conversion before the withdrawal, present only for withdrawals with conversion

blockchain
internal
exchange

Hide child attributes

transactions.id

integer

required

Transaction ID.

transactions.currency

string

required

Code of the withdrawn currency. See API currency codes.

transactions.transaction_type

enum<string>

required

Available options:

blockchain

transactions.type

string

required

Transaction type, for example withdrawal.

transactions.address

string

required

Destination address.

transactions.tag

string | null

required

Destination tag/memo. null if the withdrawal has none, for example for a currency that doesn't use tags.

transactions.amount

string

required

Amount withdrawn, in currency. In a pending withdrawal with conversion, 0 until the conversion happens.

transactions.txid

string | null

required

Blockchain transaction hash. null until the transaction is sent to the blockchain.

transactions.confirmations

string

required

Number of blockchain confirmations.

transactions.riskscore

string | null

Risk score of the transaction. null or omitted when the transaction hasn't been scored.

fees

object[]

required

Fees charged for the withdrawal. Empty when no fee is charged.

Hide child attributes

fees.type

string

required

Fee type, for example:

mining: the network fee of an on-chain withdrawal. For an instant withdrawal with conversion, it's charged in the currency taken from your balance
fee_crypto_withdrawal: a withdrawal without conversion
fee_crypto_withdrawal_from_crypto or fee_crypto_withdrawal_from_fiat: a withdrawal with conversion from a cryptocurrency or from fiat
fee_crypto_withdrawal_internal, fee_crypto_withdrawal_from_crypto_internal and fee_crypto_withdrawal_from_fiat_internal: the same for off-chain withdrawals

fees.currency

string

required

Code of the currency in which the fee was charged. See API currency codes.

fees.amount

string

required

Fee amount.

error

string

required

The reason the withdrawal was declined or cancelled. Empty string otherwise. For declined withdrawals, the value is Declined by user ID:<id>: the withdrawal wasn't approved and was declined by the user with this ID.

status

enum<string>

required

Use this field to determine whether the withdrawal was successful. For cancelled and declined withdrawals, use the error field to determine the reason.

confirmed: the withdrawal has been completed and can be treated as final on your side
pending: the withdrawal is awaiting approval, because it exceeds your withdrawal limits or because manual moderation is enabled for all withdrawals, or for all withdrawals in that currency.

In a withdrawal with conversion, the conversion hasn't happened yet, so the withdrawal transaction's amount and the exchange transaction's amount_to are 0 until it does
declined: the withdrawal was awaiting approval (pending) and was declined
cancelled: the withdrawal was cancelled and will not be completed. Common reasons, as returned in the error field:
- Address is invalid: there is a mistake in the specified address, and it does not match the format required for the specific currency
- Not enough money on balance: at the time of initiating the withdrawal, you did not have enough funds in the balance of the currency being withdrawn. Top up the balance and reinitiate the withdrawal. Automatic conversion is not possible for security reasons, so the balance must be in the exact currency being withdrawn and you must convert the funds manually
- Total of negative balances exceeds the allowed value: the total negative balances across all currencies exceed <amount>. Top up your balance and reinitiate the withdrawal
- Destination account tag is required: the destination address requires a tag (also called a memo or destination tag) to send the funds to the correct recipient, but none was provided in the withdrawal request. Specify the required tag and reinitiate the withdrawal
- Withdrawal to the address `<address>` is forbidden: the funds can't be sent to this address

No callbacks are sent while a withdrawal is processing. A confirmed callback is sent once the transaction is sent to the blockchain, and a cancelled callback if the withdrawal fails.

Available options:

confirmed,

pending,

declined,

cancelled

end_user_reference

string

The end_user_reference you provided when creating the withdrawal via the API. Use it to identify the customer who received the withdrawn funds. Absent for withdrawals initiated in the portal.

currency_sent

object

The currency and amount taken from your balance. Present only in confirmed callbacks, both for withdrawals with and without conversion.

Hide child attributes

currency_sent.currency

string

required

Code of the currency taken from your balance. See API currency codes.

currency_sent.amount

string

required

Amount taken from your balance.

currency_received

object

The currency and amount sent to the address. Present only in confirmed callbacks, both for withdrawals with and without conversion.

Hide child attributes

currency_received.currency

string

required

Code of the currency sent to the address. See API currency codes.

currency_received.amount

string

required

Amount sent.

origin

enum<string>

Present only for withdrawals initiated in the portal, including individual withdrawals from a mass payout. These callbacks are sent only if business wallet transactions callbacks are enabled in Configure callbacks.

Available options:

business_wallet

note

string

The note added to the withdrawal in the portal, or in the Note column of a mass payout file. Present only if the withdrawal has a note. A note longer than 500 characters is cut to its first 497 characters followed by ....

Reference

Deposits

Withdrawals

Payment requests

Exchanges

Currencies

Transactions

Account balance

System Health

Body