Transfer

string

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.

string

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_token

requiredstring

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

requiredstring

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

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. Defaults to the account configured during onboarding. You can find your list of funding_account_ids in the Accounts page of your Plaid Dashboard, under the "Account ID" column.

type

requiredstring

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: debit, credit

requiredstring

The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp

requiredstring

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

user

requiredobject

The legal name and other information for the account holder. The user.legal_name field is required. Other fields are not currently used and are present to support planned future functionality.

requiredstring

The user's legal name. If the user is a business, provide the business name.

string

The user's phone number.

string

The user's email address.

object

The address associated with the account holder.

string

The street number and name (i.e., "100 Market St.").

city

string

Ex. "San Francisco"

string

The state or province (e.g., "CA").

string

The postal code (e.g., "94103").

string

A two-letter country code (e.g., "US").

device

object

Information about the device being used to initiate the authorization. These fields are not currently incorporated into the risk check.

ip_address

string

The IP address of the device being used to initiate the authorization.

user_agent

string

The user agent of the device being used to initiate the authorization.

string

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

idempotency_key

string

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.

Max length: 50

user_present

boolean

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.

string

The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a third-party sender (TPS).

string

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: sweep, prefunded_rtp_credits, prefunded_ach_credits, null

test_clock_id

string

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.

/transfer/authorization/create
Select Language
1const request: TransferAuthorizationCreateRequest = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4  type: 'credit',
5  network: 'ach',
6  amount: '12.34',
7  ach_class: 'ppd',
8  user: {
9    legal_name: 'Anne Charleston',
10  },
11};
12
13try {
14  const response = await client.transferAuthorizationCreate(request);
15  const authorizationId = response.data.authorization.id;
16} catch (error) {
17  // handle error
18}

transfer/authorization/create

Response fields and example

authorization

object

Contains the authorization decision for a proposed transfer.

id

string

Plaid’s unique identifier for a transfer authorization.

string

The datetime representing when the authorization was created, in the format 2006-01-02T15:04:05Z.

Format: date-time

decision

string

A decision regarding the proposed transfer.
approved – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
declined – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: approved, declined

decision_rationale

nullableobject

The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.

code

string

A code representing the rationale for approving or declining the proposed transfer.
If the rationale_code is null, the transfer passed the authorization check.
Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link in update mode.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available.
ERROR – Unable to collect the account information due to an unspecified error.
The following codes indicate that the authorization decision was declined:
NSF – Transaction likely to result in a return due to insufficient funds.
RISK - Transaction is high-risk.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM, null

bank_initiated_return_score

string

A human-readable description of the code associated with a transfer approval or transfer decline.

payment_risk

nullableobject

This object includes the scores and risk level. This response is offered as an add-on to /transfer/authorization/create. To request access to these fields please contact your Plaid account manager.

nullableinteger

A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.
The score evaluates the transaction return risk because an account is overdrawn or because an ineligible account is used and covers return codes: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.

Minimum: 1

Maximum: 99

customer_initiated_return_score

nullableinteger

A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.
The score evaluates the transaction return risk of an unauthorized debit and covers return codes: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.

Minimum: 1

Maximum: 99

risk_level

nullablestring

Comprises five risk categories (high risk, medium-high risk, medium risk, medium-low risk, low risk) based on the probability of return

Possible values: HIGH_RISK, MEDIUM_HIGH_RISK, MEDIUM_RISK, MEDIUM_LOW_RISK, LOW_RISK

warnings

[object]

If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.

warning_type

string

A broad categorization of the warning. Safe for programmatic use.

warning_code

string

The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the ITEM_LOGIN_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.

warning_message

string

A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.

proposed_transfer

object

Details regarding the proposed transfer.

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

string

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

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

type

string

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: debit, credit

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

string

The network or rails used for the transfer.

string

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

nullablestring

The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).

nullablestring

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: sweep, prefunded_rtp_credits, prefunded_ach_credits, null

string

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

API Object
1{
"authorization": {
  "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "created": "2020-08-06T17:27:15Z",
  "decision": "approved",
  "decision_rationale": null,
  "guarantee_decision": null,
  "guarantee_decision_rationale": null,
  "payment_risk": null,
  "proposed_transfer": {
    "ach_class": "ppd",
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "type": "credit",
    "user": {
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "email_address": "acharleston@email.com",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "amount": "12.34",
    "network": "ach",
    "iso_currency_code": "USD",
    "origination_account_id": "",
    "originator_client_id": null,
    "credit_funds_source": "sweep"
  }
},
"request_id": "saKrIBuEB9qJZno"
36}

Was this helpful?

Retrieve a balance held with Plaid

Use the /transfer/balance/get endpoint to view a balance held with Plaid.

transfer/balance/get

Request fields and example

string

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.

string

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.

type

string

The type of balance.
prefunded_rtp_credits - Your prefunded RTP credit balance with Plaid prefunded_ach_credits - Your prefunded ACH credit balance with Plaid

Possible values: prefunded_rtp_credits, prefunded_ach_credits

/transfer/balance/get
Select Language
1const request: TransferBalanceGetRequest = {
2  type: 'prefunded_rtp_credits',
3};
4
5try {
6  const response = await client.transferBalanceGet(request);
7  const available_balance = response.data.balance.available;
8} catch (error) {
9  // handle error
10}

transfer/balance/get

Response fields and example

balance

object

Information about the balance held with Plaid.

available

string

The amount of this balance available for use (decimal string with two digits of precision e.g. "10.00").

current

string

The available balance, plus amount of pending funds that in processing (decimal string with two digits of precision e.g. "10.00").

type

string

The type of balance.
prefunded_rtp_credits - Your prefunded RTP credit balance with Plaid prefunded_ach_credits - Your prefunded ACH credit balance with Plaid

Possible values: prefunded_rtp_credits, prefunded_ach_credits

string

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

API Object
1{
2  "balance": {
3    "available": "1721.70",
4    "type": "prefunded_rtp_credits"
5  },
6  "request_id": "saKrIBuEB9qJZno"
7}

Was this helpful?

Get RTP eligibility information of a transfer

Use the /transfer/capabilities/get endpoint to determine the RTP eligibility information of a transfer.

transfer/capabilities/get

Request fields and example

string

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.

string

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_token

string

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

institution_supported_networks

string

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

/transfer/capabilities/get
Select Language
1const request: TransferCapabilitiesGetRequest = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4};
5
6try {
7  const response = await client.transferAuthorizationCreate(request);
8  const authorizationId = response.data.authorization.id;
9} catch (error) {
10  // handle error
11}

transfer/capabilities/get

Response fields and example

object

Contains the RTP network and types supported by the linked Item's institution.

rtp

object

Contains the supported service types in RTP

credit

boolean

When true, the linked Item's institution supports RTP credit transfer.

Default: false

string

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

API Object
1{
2  "institution_supported_networks": {
3    "rtp": {
4      "credit": true
5    }
6  },
7  "request_id": "saKrIBuEB9qJZno"
8}

Was this helpful?

Get transfer product configuration

Use the /transfer/configuration/get endpoint to view your transfer product configurations.

transfer/configuration/get

Request fields and example

string

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.

string

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.

string

The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).

/transfer/configuration/get
Select Language
1const request: TransferConfigurationGetRequest = {
2  originator_client_id: '61b8f48ded273e001aa8db6d',
3};
4
5try {
6  const response = await client.transferConfigurationGet(request);
7} catch (error) {
8  // handle error
9}

transfer/configuration/get

Response fields and example

max_single_transfer_amount

string

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

string

The max limit of dollar amount of a single transfer (decimal string with two digits of precision e.g. "10.00").

max_single_transfer_credit_amount

string

The max limit of dollar amount of a single credit transfer (decimal string with two digits of precision e.g. "10.00").

max_single_transfer_debit_amount

string

The max limit of dollar amount of a single debit transfer (decimal string with two digits of precision e.g. "10.00").

max_daily_credit_amount

string

The max limit of sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

max_daily_debit_amount

string

The max limit of sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

max_monthly_amount

string

The max limit of sum of dollar amount of credit and debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").

max_monthly_credit_amount

string

The max limit of sum of dollar amount of credit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").

max_monthly_debit_amount

string

The max limit of sum of dollar amount of debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00").

string

The currency of the dollar amount, e.g. "USD".

API Object
1{
"max_single_transfer_amount": "1000.00",
"max_single_transfer_credit_amount": "1000.00",
"max_single_transfer_debit_amount": "1000.00",
"max_daily_credit_amount": "50000.00",
"max_daily_debit_amount": "50000.00",
"max_monthly_amount": "500000.00",
"max_monthly_credit_amount": "500000.00",
"max_monthly_debit_amount": "500000.00",
"iso_currency_code": "USD",
"request_id": "saKrIBuEB9qJZno"
12}

Was this helpful?

Create a transfer

Use the /transfer/create endpoint to initiate a new transfer.

transfer/create

Request fields and example

string

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.

string

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_token

string

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

string

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

requiredstring

Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

requiredstring

The transfer description. Maximum of 15 characters. If reprocessing a returned transfer, please note that the description field must be "Retry" to indicate that it's a retry of a previously returned transfer. 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. For a full listing of ACH return codes, see Transfer errors.

Max length: 15

object

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

test_clock_id

string

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.

/transfer/create
Select Language
1const request: TransferCreateRequest = {
2  amount: '12.34',
3  description: 'payment',
4  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
5  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
6  authorization_id: '231h012308h3101z21909sw',
7};
8try {
9  const response = await client.transferCreate(request);
10  const transfer = response.data.transfer;
11} catch (error) {
12  // handle error
13}

transfer/create

Response fields and example

transfer

object

Represents a transfer within the Transfers API.

id

string

Plaid’s unique identifier for a transfer.

string

Plaid’s unique identifier for a transfer authorization.

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

string

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

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

type

string

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: debit, credit

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

string

The description of the transfer.

string

The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

string

The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned

sweep_status

nullablestring

The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept

string

The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp

cancellable

boolean

When true, you can still cancel this transfer.

nullableobject

The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

nullableobject

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

unauthorized_return_window

string

The currency of the transfer amount, e.g. "USD"

standard_return_window

nullablestring

The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date

expected_settlement_date

nullablestring

The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).

refunds

[object]

A list of refunds associated with this transfer.

id

string

Plaid’s unique identifier for a refund.

string

The ID of the transfer to refund.

string

The amount of the refund (decimal string with two digits of precision e.g. "10.00").

string

The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned

nullableobject

The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

expected_sweep_settlement_schedule

string

The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

recurring_transfer_id

nullablestring

The id of the recurring transfer if this transfer belongs to a recurring transfer.

[object]

The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

sweep_settlement_date

string

The settlement date of a sweep for this transfer.

Format: date

swept_settled_amount

string

The accumulated amount that has been swept by sweep_settlement_date.

nullablestring

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: sweep, prefunded_rtp_credits, prefunded_ach_credits, null

string

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

API Object
1{
"transfer": {
  "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
  "ach_class": "ppd",
  "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
  "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
  "type": "credit",
  "user": {
    "legal_name": "Anne Charleston",
    "phone_number": "510-555-0128",
    "email_address": "acharleston@email.com",
    "address": {
      "street": "123 Main St.",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94053",
      "country": "US"
    }
  },
  "amount": "12.34",
  "description": "payment",
  "created": "2020-08-06T17:27:15Z",
  "refunds": [],
  "status": "pending",
  "network": "ach",
  "cancellable": true,
  "guarantee_decision": null,
  "guarantee_decision_rationale": null,
  "failure_reason": null,
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "origination_account_id": "",
  "iso_currency_code": "USD",
  "standard_return_window": "2023-08-07",
  "unauthorized_return_window": "2023-10-07",
  "expected_settlement_date": "2023-08-04",
  "originator_client_id": "569ed2f36b3a3a021713abc1",
  "recurring_transfer_id": null,
  "credit_funds_source": "sweep"
},
"request_id": "saKrIBuEB9qJZno"
45}

Was this helpful?

Cancel a transfer

Use the /transfer/cancel endpoint to cancel a transfer. A transfer is eligible for cancellation if the cancellable property returned by /transfer/get is true.

transfer/cancel

Request fields and example

string

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.

string

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.

requiredstring

Plaid’s unique identifier for a transfer.

/transfer/cancel
Select Language
1const request: TransferCancelRequest = {
2  transfer_id: '123004561178933',
3};
4try {
5  const response = await plaidClient.transferCancel(request);
6  const request_id = response.data.request_id;
7} catch (error) {
8  // handle error
9}

transfer/cancel

Response fields and example

string

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

API Object
1{
2  "request_id": "saKrIBuEB9qJZno"
3}

Was this helpful?

Retrieve a transfer

The /transfer/get endpoint fetches information about the transfer corresponding to the given transfer_id.

transfer/get

Request fields and example

string

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.

string

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.

requiredstring

Plaid’s unique identifier for a transfer.

/transfer/get
Select Language
1const request: TransferGetRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}

transfer/get

Response fields and example

transfer

object

Represents a transfer within the Transfers API.

id

string

Plaid’s unique identifier for a transfer.

string

Plaid’s unique identifier for a transfer authorization.

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

string

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

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

type

string

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: debit, credit

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

string

The description of the transfer.

string

The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

string

The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned

sweep_status

nullablestring

The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept

string

The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp

cancellable

boolean

When true, you can still cancel this transfer.

nullableobject

The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

nullableobject

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

unauthorized_return_window

string

The currency of the transfer amount, e.g. "USD"

standard_return_window

nullablestring

The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date

expected_settlement_date

nullablestring

The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).

refunds

[object]

A list of refunds associated with this transfer.

id

string

Plaid’s unique identifier for a refund.

string

The ID of the transfer to refund.

string

The amount of the refund (decimal string with two digits of precision e.g. "10.00").

string

The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned

nullableobject

The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

expected_sweep_settlement_schedule

string

The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

recurring_transfer_id

nullablestring

The id of the recurring transfer if this transfer belongs to a recurring transfer.

[object]

The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

sweep_settlement_date

string

The settlement date of a sweep for this transfer.

Format: date

swept_settled_amount

string

The accumulated amount that has been swept by sweep_settlement_date.

nullablestring

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: sweep, prefunded_rtp_credits, prefunded_ach_credits, null

string

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

API Object
1{
"transfer": {
  "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
  "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
  "ach_class": "ppd",
  "amount": "12.34",
  "cancellable": true,
  "created": "2020-08-06T17:27:15Z",
  "description": "Desc",
  "guarantee_decision": null,
  "guarantee_decision_rationale": null,
  "failure_reason": {
    "ach_return_code": "R13",
    "description": "Invalid ACH routing number"
  },
  "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "network": "ach",
  "origination_account_id": "",
  "originator_client_id": null,
  "refunds": [],
  "status": "pending",
  "type": "credit",
  "iso_currency_code": "USD",
  "standard_return_window": "2020-08-07",
  "unauthorized_return_window": "2020-10-07",
  "expected_settlement_date": "2020-08-04",
  "user": {
    "email_address": "acharleston@email.com",
    "legal_name": "Anne Charleston",
    "phone_number": "510-555-0128",
    "address": {
      "street": "123 Main St.",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94053",
      "country": "US"
    }
  },
  "recurring_transfer_id": null,
  "credit_funds_source": "sweep"
},
"request_id": "saKrIBuEB9qJZno"
48}

Was this helpful?

List transfers

Use the /transfer/list endpoint to see a list of all your transfers and their statuses. Results are paginated; use the count and offset query parameters to retrieve the desired transfers.

transfer/list

Request fields and example

string

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.

string

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.

start_date

string

The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time

end_date

string

The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time

integer

The maximum number of transfers to return.

Minimum: 1

Maximum: 25

Default: 25

offset

integer

The number of transfers to skip before returning results.

Default: 0

Minimum: 0

string

Filter transfers to only those with the specified originator client.

string

Filter transfers to only those with the specified funding_account_id.

/transfer/list
Select Language
1const request: TransferListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
7};
8try {
9  const response = await plaidClient.transferList(request);
10  const transfers = response.data.transfers;
11  for (const transfer of transfers) {
12    // iterate through transfers
13  }
14} catch (error) {
15  // handle error
16}

transfer/list

Response fields and example

transfers

[object]

id

string

Plaid’s unique identifier for a transfer.

string

Plaid’s unique identifier for a transfer authorization.

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

string

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

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

type

string

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: debit, credit

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

string

The description of the transfer.

string

The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

string

The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned

sweep_status

nullablestring

The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept

string

The network or rails used for the transfer.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp

cancellable

boolean

When true, you can still cancel this transfer.

nullableobject

The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

nullableobject

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

unauthorized_return_window

string

The currency of the transfer amount, e.g. "USD"

standard_return_window

nullablestring

The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date

expected_settlement_date

nullablestring

The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date

nullablestring

The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a third-party sender (TPS).

refunds

[object]

A list of refunds associated with this transfer.

id

string

Plaid’s unique identifier for a refund.

string

The ID of the transfer to refund.

string

The amount of the refund (decimal string with two digits of precision e.g. "10.00").

string

The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned

nullableobject

The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

expected_sweep_settlement_schedule

string

The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time

recurring_transfer_id

nullablestring

The id of the recurring transfer if this transfer belongs to a recurring transfer.

[object]

The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.

sweep_settlement_date

string

The settlement date of a sweep for this transfer.

Format: date

swept_settled_amount

string

The accumulated amount that has been swept by sweep_settlement_date.

nullablestring

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: sweep, prefunded_rtp_credits, prefunded_ach_credits, null

string

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

API Object
1{
"transfers": [
  {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "ach_class": "ppd",
    "amount": "12.34",
    "cancellable": true,
    "created": "2019-12-09T17:27:15Z",
    "description": "Desc",
    "guarantee_decision": null,
    "guarantee_decision_rationale": null,
    "failure_reason": {
      "ach_return_code": "R13",
      "description": "Invalid ACH routing number"
    },
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "network": "ach",
    "origination_account_id": "",
    "originator_client_id": null,
    "refunds": [],
    "status": "pending",
    "type": "credit",
    "iso_currency_code": "USD",
    "standard_return_window": "2020-08-07",
    "unauthorized_return_window": "2020-10-07",
    "expected_settlement_date": "2020-08-04",
    "user": {
      "email_address": "acharleston@email.com",
      "legal_name": "Anne Charleston",
      "phone_number": "510-555-0128",
      "address": {
        "street": "123 Main St.",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94053",
        "country": "US"
      }
    },
    "recurring_transfer_id": null,
    "credit_funds_source": "sweep"
  }
],
"request_id": "saKrIBuEB9qJZno"
50}

Was this helpful?

List transfer events

Use the /transfer/event/list endpoint to get a list of transfer events based on specified filter criteria.

transfer/event/list

Request fields and example

string

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.

string

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.

start_date

string

The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time

end_date

string

The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time

string

Plaid’s unique identifier for a transfer.

string

The account ID to get events for all transactions to/from an account.

transfer_type

string

The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account.

Possible values: debit, credit, null

event_types

[string]

Filter events by event type.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed

string

Plaid’s unique identifier for a sweep.

integer

The maximum number of transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned.

Default: 25

Maximum: 25

Minimum: 1

offset

integer

The offset into the list of transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 events will be returned.

Default: 0

Minimum: 0

string

Filter transfer events to only those with the specified originator client.

string

Filter transfer events to only those with the specified funding_account_id.

/transfer/event/list
Select Language
1const request: TransferEventListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
5  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
6  transfer_type: 'credit',
7  event_types: ['pending', 'posted'],
8  count: 14,
9  offset: 2,
10  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
11};
12try {
13  const response = await plaidClient.transferEventList(request);
14  const events = response.data.transfer_events;
15  for (const event of events) {
16    // iterate through events
17  }
18} catch (error) {
19  // handle error
20}

transfer/event/list

Response fields and example

transfer_events

[object]

event_id

integer

Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0

timestamp

string

The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time

event_type

string

The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.
sweep.pending: A new ledger sweep was created; it is in the pending state.
sweep.posted: The ledger sweep has been successfully submitted to the payment network.
sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun.
sweep.returned: A posted ledger sweep was returned.
sweep.failed: The ledger sweep failed, no funds were moved.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed

string

The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

string

Plaid’s unique identifier for a transfer. This field is null for Plaid Ledger Sweep events.

transfer_type

string

The type of transfer. Valid values are 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. This field is omitted for Plaid Ledger Sweep events.

Possible values: debit, credit

transfer_amount

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.

nullableobject

The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

nullablestring

Plaid’s unique identifier for a sweep.

sweep_amount

nullablestring

A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").

refund_id

nullablestring

Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.

nullablestring

The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).

string

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

API Object
1{
"transfer_events": [
  {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "transfer_amount": "12.34",
    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "transfer_type": "credit",
    "event_id": 1,
    "event_type": "posted",
    "failure_reason": null,
    "origination_account_id": "",
    "originator_client_id": "569ed2f36b3a3a021713abc1",
    "refund_id": null,
    "sweep_amount": null,
    "sweep_id": null,
    "timestamp": "2019-12-09T17:27:15Z"
  }
],
"request_id": "mdqfuVxeoza6mhu"
21}

Was this helpful?

Get transfer product usage metrics

Use the /transfer/metrics/get endpoint to view your transfer product usage metrics.

transfer/metrics/get

Request fields and example

string

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.

string

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.

string

The Plaid client ID of the transfer originator. Should only be present if client_id is a third-party sender (TPS).

/transfer/metrics/get
Select Language
1const request: TransferMetricsGetRequest = {
2  originator_client_id: '61b8f48ded273e001aa8db6d',
3};
4
5try {
6  const response = await client.transferMetricsGet(request);
7} catch (error) {
8  // handle error
9}

transfer/metrics/get

Response fields and example

daily_debit_transfer_volume

string

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

string

Sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

daily_credit_transfer_volume

string

Sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00").

monthly_transfer_volume

string

Sum of dollar amount of credit and debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").

monthly_debit_transfer_volume

string

Sum of dollar amount of debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").

monthly_credit_transfer_volume

string

Sum of dollar amount of credit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00").

string

The currency of the dollar amount, e.g. "USD".

API Object
1{
"daily_debit_transfer_volume": "1234.56",
"daily_credit_transfer_volume": "567.89",
"monthly_transfer_volume": "12345.67",
"monthly_debit_transfer_volume": "10000.00",
"monthly_credit_transfer_volume": "2345.67",
"iso_currency_code": "USD",
"request_id": "saKrIBuEB9qJZno"
9}

Was this helpful?

Sync transfer events

/transfer/event/sync allows you to request up to the next 25 transfer events that happened after a specific event_id. Use the /transfer/event/sync endpoint to guarantee you have seen all transfer events.

transfer/event/sync

Request fields and example

string

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.

string

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.

after_id

requiredinteger

The latest (largest) event_id fetched via the sync endpoint, or 0 initially.

Minimum: 0

integer

The maximum number of transfer events to return.

Default: 25

Minimum: 1

Maximum: 25

/transfer/event/sync
Select Language
1const request: TransferEventListRequest = {
2  after_id: 4,
3  count: 22,
4};
5try {
6  const response = await plaidClient.transferEventSync(request);
7  const events = response.data.transfer_events;
8  for (const event of events) {
9    // iterate through events
10  }
11} catch (error) {
12  // handle error
13}

transfer/event/sync

Response fields and example

transfer_events

[object]

event_id

integer

Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

Minimum: 0

timestamp

string

The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time

event_type

string

The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.
sweep.pending: A new ledger sweep was created; it is in the pending state.
sweep.posted: The ledger sweep has been successfully submitted to the payment network.
sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun.
sweep.returned: A posted ledger sweep was returned.
sweep.failed: The ledger sweep failed, no funds were moved.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed

string

The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.

nullablestring

The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.

string

Plaid’s unique identifier for a transfer. This field is null for Plaid Ledger Sweep events.

transfer_type

string

The type of transfer. Valid values are 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. This field is omitted for Plaid Ledger Sweep events.

Possible values: debit, credit

transfer_amount

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.

nullableobject

The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.

nullablestring

The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.

string

A human-readable description of the reason for the failure or reversal.

nullablestring

Plaid’s unique identifier for a sweep.

sweep_amount

nullablestring

A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").

refund_id

nullablestring

Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.

nullablestring

The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).

string

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

API Object
1{
"transfer_events": [
  {
    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "transfer_amount": "12.34",
    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "transfer_type": "credit",
    "event_id": 1,
    "event_type": "pending",
    "failure_reason": null,
    "origination_account_id": "",
    "originator_client_id": null,
    "refund_id": null,
    "sweep_amount": null,
    "sweep_id": null,
    "timestamp": "2019-12-09T17:27:15Z"
  }
],
"request_id": "mdqfuVxeoza6mhu"
21}

Was this helpful?

Retrieve a sweep

The /transfer/sweep/get endpoint fetches a sweep corresponding to the given sweep_id.

transfer/sweep/get

Request fields and example

string

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.

string

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.

requiredstring

Plaid's unique identifier for the sweep (UUID) or a shortened form consisting of the first 8 characters of the identifier (8-digit hexadecimal string).

/transfer/sweep/get
Select Language
1const request: TransferSweepGetRequest = {
2  sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee',
3};
4try {
5  const response = await plaidClient.transferSweepGet(request);
6  const sweep = response.data.sweep;
7} catch (error) {
8  // handle error
9}

transfer/sweep/get

Response fields and example

sweep

object

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.

id

string

Identifier of the sweep.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

string

The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time

string

Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

string

The currency of the sweep, e.g. "USD".

settled

nullablestring

The date when the sweep settled, in the YYYY-MM-DD format.

Format: date

nullablestring

The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null

trigger

nullablestring

The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate

string

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.

string

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

API Object
1{
"sweep": {
  "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
  "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
  "created": "2020-08-06T17:27:15Z",
  "amount": "12.34",
  "iso_currency_code": "USD",
  "settled": "2020-08-07",
  "status": "settled"
},
"request_id": "saKrIBuEB9qJZno"
12}

Was this helpful?

List sweeps

The /transfer/sweep/list endpoint fetches sweeps matching the given filters.

transfer/sweep/list

Request fields and example

string

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.

string

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.

start_date

string

The start datetime of sweeps to return (RFC 3339 format).

Format: date-time

end_date

string

The end datetime of sweeps to return (RFC 3339 format).

Format: date-time

integer

The maximum number of sweeps to return.

Minimum: 1

Maximum: 25

Default: 25

offset

integer

The number of sweeps to skip before returning results.

Default: 0

Minimum: 0

string

Filter sweeps to only those with the specified amount.

string

The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null

string

Filter sweeps to only those with the specified originator client.

string

Filter sweeps to only those with the specified funding_account_id.

string

Filter sweeps to only those with the included transfer_id.

trigger

string

The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate

/transfer/sweep/list
Select Language
1const request: TransferSweepListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6};
7try {
8  const response = await plaidClient.transferSweepList(request);
9  const sweeps = response.data.sweeps;
10  for (const sweep of sweeps) {
11    // iterate through sweeps
12  }
13} catch (error) {
14  // handle error
15}

transfer/sweep/list

Response fields and example

sweeps

[object]

id

string

Identifier of the sweep.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

string

The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time

string

Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

string

The currency of the sweep, e.g. "USD".

settled

nullablestring

The date when the sweep settled, in the YYYY-MM-DD format.

Format: date

nullablestring

The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null

trigger

nullablestring

The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate

string

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.

string

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

API Object
1{
"sweeps": [
  {
    "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
    "created": "2019-12-09T17:27:15Z",
    "amount": "-12.34",
    "iso_currency_code": "USD",
    "settled": "2019-12-10",
    "status": "settled",
    "originator_client_id": null
  }
],
"request_id": "saKrIBuEB9qJZno"
15}

Was this helpful?

Create a transfer intent object to invoke the Transfer UI

Use the /transfer/intent/create endpoint to generate a transfer intent object and invoke the Transfer UI.

transfer/intent/create

Request fields and example

string

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.

string

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.

string

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

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. Defaults to the account configured during onboarding. You can find your list of funding_account_ids in the Accounts page of your Plaid Dashboard, under the "Account ID" column.

mode

requiredstring

The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT

string

The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach

Default: same-day-ach

requiredstring

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

requiredstring

A description for the underlying transfer. Maximum of 8 characters.

Min length: 1

Max length: 8

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

user

requiredobject

The legal name and other information for the account holder.

requiredstring

The user's legal name.

string

The user's phone number.

string

The user's email address.

object

The address associated with the account holder.

string

The street number and name (i.e., "100 Market St.").

city

string

Ex. "San Francisco"

string

The state or province (e.g., "CA").

string

The postal code (e.g., "94103").

string

A two-letter country code (e.g., "US").

object

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

string

The currency of the transfer amount, e.g. "USD"

/transfer/intent/create
Select Language
1const request: TransferIntentCreateRequest = {
2  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
3  mode: 'PAYMENT'
4  amount: '12.34',
5  description: 'Desc',
6  ach_class: 'ppd',
7  origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359',
8  user: {
9    legal_name: 'Anne Charleston',
10  },
11};
12
13try {
14  const response = await client.transferIntentCreate(request);
15} catch (error) {
16  // handle error
17}

transfer/intent/create

Response fields and example

transfer_intent

object

Represents a transfer intent within Transfer UI.

id

string

Plaid's unique identifier for the transfer intent object.

string

The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time

string

The status of the transfer intent.
PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created.

Possible values: PENDING, SUCCEEDED, FAILED

nullablestring

The Plaid account_id corresponding to the end-user account that will be debited or credited. Returned only if account_id was set on intent creation.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

mode

string

The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT

string

The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach

Default: same-day-ach

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

A description for the underlying transfer. Maximum of 8 characters.

nullableobject

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

string

The currency of the transfer amount, e.g. "USD"

string

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

API Object
1{
"transfer_intent": {
  "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
  "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
  "ach_class": "ppd",
  "amount": "12.34",
  "iso_currency_code": "USD",
  "created": "2020-08-06T17:27:15Z",
  "description": "Desc",
  "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "mode": "PAYMENT",
  "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
  "status": "PENDING",
  "user": {
    "address": {
      "street": "100 Market Street",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94103",
      "country": "US"
    },
    "email_address": "acharleston@email.com",
    "legal_name": "Anne Charleston",
    "phone_number": "123-456-7890"
  }
},
"request_id": "saKrIBuEB9qJZno"
32}

Was this helpful?

Retrieve more information about a transfer intent

Use the /transfer/intent/get endpoint to retrieve more information about a transfer intent.

transfer/intent/get

Request fields and example

string

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.

string

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.

transfer_intent_id

requiredstring

Plaid's unique identifier for a transfer intent object.

/transfer/intent/get
Select Language
1const request: TransferIntentGetRequest = {
2  transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferIntentGet(request);
7} catch (error) {
8  // handle error
9}

transfer/intent/get

Response fields and example

transfer_intent

object

Represents a transfer intent within Transfer UI.

id

string

Plaid's unique identifier for a transfer intent object.

string

The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time

string

The status of the transfer intent.
PENDING: The transfer intent is pending. SUCCEEDED: The transfer intent was successfully created. FAILED: The transfer intent was unable to be created.

Possible values: PENDING, SUCCEEDED, FAILED

nullablestring

Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise.

authorization_decision_rationale

nullableobject

The reason for a failed transfer intent. Returned only if the transfer intent status is failed. Null otherwise.

error_type

string

A broad categorization of the error.

error_code

string

A code representing the reason for a failed transfer intent (i.e., an API error or the authorization being declined).

error_message

string

A human-readable description of the code associated with a failed transfer intent.

authorization_decision

nullablestring

A decision regarding the proposed transfer.
APPROVED – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code is ITEM_LOGIN_REQUIRED). Refer to the code field in the decision_rationale object for details.
DECLINED – Plaid reviewed the proposed transfer and declined processing. Refer to the code field in the decision_rationale object for details.

Possible values: APPROVED, DECLINED

nullableobject

The rationale for Plaid's decision regarding a proposed transfer. It is always set for declined decisions, and may or may not be null for approved decisions.

code

string

A code representing the rationale for approving or declining the proposed transfer.
If the rationale_code is null, the transfer passed the authorization check.
Any non-null value for an approved transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved transfer are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be resolved by using Link in update mode.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available.
ERROR – Unable to collect the account information due to an unspecified error.
The following codes indicate that the authorization decision was declined:
NSF – Transaction likely to result in a return due to insufficient funds.
RISK - Transaction is high-risk.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM, null

string

A human-readable description of the code associated with a transfer approval or transfer decline.

nullablestring

The Plaid account_id for the account that will be debited or credited. Returned only if account_id was set on intent creation.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

string

The amount of the transfer (decimal string with two digits of precision e.g. "10.00").

mode

string

The direction of the flow of transfer funds.
PAYMENT: Transfers funds from an end user's account to your business account.
DISBURSEMENT: Transfers funds from your business account to an end user's account.

Possible values: PAYMENT, DISBURSEMENT

string

The network or rails used for the transfer. Defaults to same-day-ach.
For transfers submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.

Possible values: ach, same-day-ach

Default: same-day-ach

string

Specifies the use case of the transfer. Required for transfers on an ACH network.
"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, eg. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web

user

object

The legal name and other information for the account holder.

string

The user's legal name.

nullablestring

The user's phone number.

nullablestring

The user's email address.

nullableobject

The address associated with the account holder.

nullablestring

The street number and name (i.e., "100 Market St.").

city

nullablestring

Ex. "San Francisco"

nullablestring

The state or province (e.g., "CA").

nullablestring

The postal code (e.g., "94103").

nullablestring

A two-letter country code (e.g., "US").

string

A description for the underlying transfer. Maximum of 8 characters.

nullableobject

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

string

The currency of the transfer amount, e.g. "USD"