Sign in
plaid

Create a transfer authorization

Use the /transfer/authorization/create endpoint to authorize a transfer. This endpoint must be called prior to calling /transfer/create.

There are three 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 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 approve a transfer with the rationale code ITEM_LOGIN_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.

post/transfer/authorization/create

Request body

client_idstring

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.

secretstring

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.

access_tokenstring required

The Plaid access_token for the account that will be debited or credited.

account_idstring required

The Plaid account_id corresponding to the end-user account that will be debited or credited.

funding_account_idstring nullable

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_ids 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.

payment_profile_tokenstring

The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using access_token.

type'debit' | 'credit' required

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.

network'ach' | 'same-day-ach' | 'rtp' | 'wire' required

The network or rails used for the transfer.

For transfers submitted as ach, the next-day cutoff is 5: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.

amountstring required

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'ccd' | 'ppd' | 'tel' | 'web'

Specifies the use case of the transfer. Required for transfers on an ACH network.

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, e.g. bill payment

"tel" - Telephone-Initiated Entry

"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

origination_account_idstring

Plaid's unique identifier for the origination account for this authorization. If not specified, the default account will be used.

iso_currency_codestring

The currency of the transfer amount. The default value is "USD".

idempotency_keystring nullable

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.

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.

user_presentboolean nullable

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.

with_guaranteeboolean nullable

If set to false, Plaid will not offer a guarantee_decision for this request (Guarantee customers only).

beacon_session_idstring nullable

The unique identifier returned by Plaid's beacon when it is run on your webpage.

originator_client_idstring nullable

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.

credit_funds_source'sweep' | 'prefunded_rtp_credits' | 'prefunded_ach_credits' | 'null' nullable

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

test_clock_idstring nullable

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.

Response

OK

request_idstring required

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Changes