Sample - Plaid API
POST/transfer/create

Create a transfer

Creates a transfer using an existing transfer authorization. Supply access_token, account_id, authorization_id, and the transfer description, along with the exact authorized amount and any applicable metadata. The operation is idempotent for the authorization and can return an existing transfer when the same authorization is submitted again; use transfer events to reconcile an uncertain result.

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

17 body fields

Transfer creation details using an existing authorization and the account to debit or credit.

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.
idempotency_keystringdeprecatedoptional
Deprecated. `authorization_id` is now used as idempotency instead. A random key provided by the client, per unique transfer. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transfer fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single transfer is created.
access_tokenstringrequired
The Plaid `access_token` for the account that will be debited or credited.
account_idstringrequired
The Plaid `account_id` corresponding to the end-user account that will be debited or credited.
authorization_idstringrequired
Plaid's unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.
typeobjectdeprecatedoptional
The deprecated transfer type: `debit` or `credit`.
networkobjectdeprecatedoptional
The deprecated transfer network: `ach`, `same-day-ach`, `rtp`, `wire`, or `rfp`.
amountstringoptional
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent.
descriptionstringrequired
The transfer description, maximum of 15 characters (RTP transactions) or 10 characters (ACH transactions). Should represent why the money is moving, not your company name. For recommendations on setting the `description` field to avoid ACH returns, see [Description field recommendations](https://www.plaid.com/docs/transfer/creating-transfers/#description-field-recommendations). If reprocessing a returned transfer, the `description` field must be `"Retry 1"` or `"Retry 2"`. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code `R01` or `R09` may be retried.
ach_classobjectdeprecatedoptional
The deprecated ACH SEC code: `ccd`, `ppd`, `tel`, or `web`.
userobjectdeprecatedoptional
The legal name and other information for the account holder.
metadataobjectoptional
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
origination_account_idstringdeprecatedoptional
Plaid's unique identifier for the origination account for this transfer. If you have more than one origination account, this value must be specified. Otherwise, this field should be left blank.
iso_currency_codestringdeprecatedoptional
The currency of the transfer amount. The default value is "USD".
test_clock_idstringoptional
Plaid's unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `transfer` is created at the `virtual_time` on the provided `test_clock`.
facilitator_feestringoptional
The amount to deduct from `transfer.amount` and distribute to the platform's Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer's Ledger balance. This must be value greater than 0 and less than or equal to the `transfer.amount`.

2 status codes
200Returns the transfer object, including its identifier, authorization, amount, status, network, metadata, decision details, and request identifier.
transferobjectrequired
Represents a transfer within the Transfers API.
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

access_token, account_id, authorization_id, and description are required. description must not exceed 15 characters, metadata can contain at most 50 string key-value pairs, and deprecated fields such as idempotency_key, type, and network should not be used for new requests.