Sample - Plaid API
POST/transfer/ledger/withdraw

Withdraw funds from a Plaid Ledger

Withdraws funds from a Plaid Ledger balance to a funding account. Provide a positive amount, an idempotency key, and the transfer network; omit ledger_id or funding_account_id to use their configured defaults. The response contains the resulting sweep and its request identifier.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

9 body fields

Ledger withdrawal details, including the amount, funding route, source ledger, network, and retry-safe idempotency key.

client_idstringoptional
Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
secretstringoptional
Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
originator_client_idstringoptional
Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to pay out to or collect funds from. Only applicable for [Platform customers](https://plaid.com/docs/transfer/application/#originators-vs-platforms). Do not include if you're paying out to yourself.
funding_account_idstringoptional
Specify which funding account to use. Customers can find a list of `funding_account_id`s in the Accounts page of the Plaid Dashboard, under the "Account ID" column. If this field is left blank, the funding account associated with the specified Ledger will be used. If an `originator_client_id` is specified, the `funding_account_id` must belong to the specified originator.
ledger_idstringoptional
Specify which ledger balance to withdraw from. Customers can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to the id of the default ledger balance.
amountstringrequired
A positive amount of how much will be withdrawn from the ledger balance (decimal string with two digits of precision e.g. "5.50").
descriptionstringoptional
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.
idempotency_keystringrequired
A unique key provided by the client, per unique ledger withdraw. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger withdraw fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single withdraw is created.
networkstringrequired
The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between the Real-Time Payments (RTP) rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your account manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Support for `rfp` (request for payment) is currently in closed beta. To learn more, contact your Plaid account manager. For transfers submitted as `rfp`, the `type` must be `debit`.
Allowed:achsame-day-achrtpwirerfp

2 status codes
200Returns the created sweep, including its amount, ledger and funding account identifiers, settlement information, status, and request identifier.
sweepobjectrequired
Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type `swept` or `return_swept`) which can be retrieved by invoking the `/transfer/event/list` endpoint with the corresponding `sweep_id`. `swept` events occur when the transfer amount is credited or debited from your sweep account, depending on the `type` of the transfer. `return_swept` events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the `swept` and `return_swept` events is equal to the `amount` of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
defaultError response
error_typestringrequired
A broad categorization of the error. Safe for programmatic use.
Allowed:INVALID_REQUESTINVALID_RESULTINVALID_INPUTINSTITUTION_ERRORRATE_LIMIT_EXCEEDEDAPI_ERRORITEM_ERRORASSET_REPORT_ERRORBASE_REPORT_ERRORRECAPTCHA_ERROROAUTH_ERRORPAYMENT_ERROR
error_codestringrequired
The particular error code. Safe for programmatic use.
error_code_reasonstringoptional
The specific reason for the error code. Currently, reasons are only supported for OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user's OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user's OAuth connection to this institution is invalid because the user revoked their connection.
error_messagestringrequired
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagestringrequired
A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use.
request_idstringoptional
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarrayoptional
In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.
statusintegeroptional
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_urlstringoptional
The URL of a Plaid documentation page with more information about the error
suggested_actionstringoptional
Suggested steps for resolving the error
required_account_subtypesarray<string>optional
A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.
provided_account_subtypesarray<string>optional
A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

Error handling

amount, idempotency_key, and network are required. amount must be positive, idempotency_key must be no more than 50 characters, description must be no more than 10 characters when supplied, and network must be one of ach, same-day-ach, rtp, wire, or rfp.