Skip to navigation
API ReferenceWithdrawals

Create withdrawal

Creates a withdrawal request for a ledger account

Required permissions:

  • payout:withdraw_funds
  • payout:destination:read

Authentication

AuthorizationBearer

A company API key, company scoped JWT, app API key, or user OAuth token. You must prepend your key/token with the word ‘Bearer’, which will look like Bearer ***************************

Request

Parameters for CreateLedgerWithdrawal
amountdoubleRequired
The amount to withdraw in the specified currency
company_idstringRequired
The ID of the company to withdraw from.
currencyenumRequired
The currency that is being withdrawn.
payout_method_idstring or nullOptional
The ID of the payout method to use for the withdrawal.
platform_covers_feesboolean or nullOptional
Whether the platform covers the payout fees instead of the connected account.
statement_descriptorstring or nullOptional
Custom statement descriptor for the withdrawal. Must be between 5 and 22 characters and contain only alphanumeric characters.

Response

A successful response
amountdouble

The withdrawal amount as a decimal number in the specified currency (e.g., 100.00 for $100.00 USD).

created_atdatetime
The datetime the withdrawal was created.
currencyenum

The three-letter ISO currency code for this withdrawal (e.g., ‘usd’, ‘eur’).

error_codeenum or null

A machine-readable error code describing why the payout failed. Null if no error occurred.

error_messagestring or null

A human-readable message describing why the payout failed. Null if no error occurred.

estimated_availabilitydatetime or null
The estimated time at which the funds become available in the destination account. Null if no estimate is available. As a Unix timestamp.
fee_amountdouble
The fee charged for processing this withdrawal, in the same currency as the withdrawal amount.
fee_typeenum or null

How the fee was applied to the withdrawal. ‘exclusive’ means the fee was added on top (user receives the full requested amount). ‘inclusive’ means the fee was deducted from the withdrawal (user receives less than requested). Null if no fee was charged.

Allowed values:
idstring
The unique identifier for the withdrawal.
ledger_accountobject
The ledger account from which the withdrawal funds are sourced.
markup_feedouble
An additional markup fee charged for the withdrawal, in the same currency as the withdrawal amount. Only applies to platform accounts using Whop Rails.
payout_tokenobject or null

The saved payout destination used for this withdrawal (e.g., a bank account or PayPal address). Null if no payout token was used.

speedenum

The processing speed selected for this withdrawal (‘standard’ or ‘instant’).

Allowed values:
statusenum

The computed lifecycle status of the withdrawal, accounting for the state of associated payouts (e.g., ‘requested’, ‘in_transit’, ‘completed’, ‘failed’).

trace_codestring or null
The ACH trace number for tracking the payout through the banking network. Null if not available or not an ACH transaction.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error