POST /transfer/authorization/create

Use the /transfer/authorization/create endpoint to authorize a transfer. This endpoint must be called prior to calling /transfer/create. The transfer authorization will expire if not used after one hour. (You can contact your account manager to change the default authorization lifetime.)

There are four possible outcomes to calling this endpoint:

If the authorization.decision in the response is declined, the proposed transfer has failed the risk check and you cannot proceed with the transfer.
If the authorization.decision is user_action_required, additional user input is needed, usually to fix a broken bank connection, before Plaid can properly assess the risk. You need to launch Link in update mode to complete the required user action. When calling /link/token/create to get a new Link token, instead of providing access_token in the request, you should set transfer.authorization_id as the authorization.id. After the Link flow is completed, you may re-attempt the authorization.
If the authorization.decision is approved, and the authorization.rationale_code is null, the transfer has passed the risk check and you can proceed to call /transfer/create.
If the authorization.decision is approved and the authorization.rationale_code is non-null, the risk check could not be run: you may proceed with the transfer, but should perform your own risk evaluation. For more details, see the response schema.

In Plaid's Sandbox environment the decisions will be returned as follows:

To approve a transfer with null rationale code, make an authorization request with an amount less than the available balance in the account.
To approve a transfer with the rationale code MANUALLY_VERIFIED_ITEM, create an Item in Link through the Same Day Micro-deposits flow.
To get an authorization decision of user_action_required, reset the login for an Item.
To decline a transfer with the rationale code NSF, the available balance on the account must be less than the authorization amount. See Create Sandbox test data for details on how to customize data in Sandbox.
To decline a transfer with the rationale code RISK, the available balance on the account must be exactly $0. See Create Sandbox test data for details on how to customize data in Sandbox.

Servers

https://production.plaid.com
https://sandbox.plaid.com

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`wire_details`	Object	No	Information specific to wire transfers.
`wire_details.message_to_beneficiary`	String	No	Additional information from the wire originator to the beneficiary. Max 140 characters.
`device`	Object	No	Information about the device being used to initiate the authorization. These fields are not currently incorporated into the risk check.
`device.ip_address`	String	No	The IP address of the device being used to initiate the authorization.
`device.user_agent`	String	No	The user agent of the device being used to initiate the authorization.
`network`	String	Yes	The network or rails used for the transfer. For transfers submitted as `ach`, the next-day cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment 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 4: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. Possible values: `"ach"` `"rtp"` `"same-day-ach"` `"wire"`
`with_guarantee`	Boolean	No	If set to `false`, Plaid will not offer a `guarantee_decision` for this request (Guarantee customers only). Default value: true
`client_id`	String	No	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.
`ruleset_key`	String	No	The key of the Ruleset for the transaction. This feature is currently in closed beta; to request access, contact your account manager.
`ledger_id`	String	No	Specify which ledger balance used to fund the transfer. 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 id of the default ledger balance.
`user_present`	Boolean	No	If the end user is initiating the specific transfer themselves via an interactive UI, this should be `true`; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be `false`. This field is not currently used and is present to support planned future functionality.
`test_clock_id`	String	No	Plaid’s unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `authorization` is created at the `virtual_time` on the provided test clock.
`idempotency_key`	String	No	A random key provided by the client, per unique authorization, which expires after 48 hours. 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 an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created. Idempotency does not apply to authorizations whose decisions are `user_action_required`. Therefore you may re-attempt the authorization after completing the required user action without changing `idempotency_key`. This idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges.
`iso_currency_code`	String	No	The currency of the transfer amount. The default value is "USD".
`credit_funds_source`	String	No	This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid Possible values: `"prefunded_rtp_credits"` `null` `"sweep"` `"prefunded_ach_credits"`
`user`	Object	Yes	The legal name and other information for the account holder. If the account has multiple account holders, provide the information for the account holder on whose behalf the authorization is being requested. The `user.legal_name` field is required. Other fields are not currently used and are present to support planned future functionality.
`user.email_address`	String	No	The user's email address.
`user.legal_name`	String	Yes	The user's legal name. If the user is a business, provide the business name.
`user.address`	Object	No	The address associated with the account holder.
`user.address.region`	String	No	The state or province (e.g., "CA").
`user.address.postal_code`	String	No	The postal code (e.g., "94103").
`user.address.country`	String	No	A two-letter country code (e.g., "US").
`user.address.street`	String	No	The street number and name (i.e., "100 Market St.").
`user.address.city`	String	No	Ex. "San Francisco"
`user.phone_number`	String	No	The user's phone number.
`origination_account_id`	String	No	Plaid's unique identifier for the origination account for this authorization. If not specified, the default account will be used.
`amount`	String	Yes	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.
`ach_class`	String	No	Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes. Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `"ppd"` `"web"` `"tel"` `"ccd"`
`beacon_session_id`	String	No	The unique identifier returned by Plaid's beacon when it is run on your webpage.
`type`	String	Yes	The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `"credit"` `"debit"`
`funding_account_id`	String	No	Specify the account used to fund the transfer. Should be specified if using legacy funding methods only. If using Plaid Ledger, leave this field blank. Customers can find a list of `funding_account_id`s in the Accounts page of your Plaid Dashboard, under the "Account ID" column. If this field is left blank and you are using legacy funding methods, this will default to the default `funding_account_id` specified during onboarding. Otherwise, Plaid Ledger will be used.
`account_id`	String	Yes	The Plaid `account_id` corresponding to the end-user account that will be debited or credited.
`payment_profile_token`	String	No	The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using `access_token`.
`access_token`	String	Yes	The Plaid `access_token` for the account that will be debited or credited.
`secret`	String	No	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_id`	String	No	The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a Platform customer.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.