Transfer (beta)

API reference for Transfer endpoints and webhooks

Intelligently process transfers between accounts in the US.

Only supported in Plaid's Sandbox and Production environments.

Endpoints
/transfer/authorization/createCreate a transfer authorization
/transfer/createCreate a transfer
/transfer/cancelCancel a transfer
/transfer/getRetrieve information about a transfer
/transfer/listRetrieve a list of transfers and their statuses
/transfer/event/listRetrieve a list of transfer events
/transfer/event/syncSync transfer events
/transfer/sweep/getRetrieve information about a sweep
/transfer/sweep/listRetrieve a list of sweeps
/transfer/intent/createCreate a transfer intent and invoke Transfer UI (Transfer UI only)
/transfer/intent/getRetrieve information about a transfer intent (Transfer UI only)
/transfer/refund/createCreate a refund for a transfer
/transfer/refund/cancelCancel a refund
/transfer/refund/getRetrieve information about a refund
/transfer/migrate_accountCreate an Item to use with Transfer from known account and routing numbers
/payment_profile/createCreate a Payment Profile
/payment_profile/removeRemove a Payment Profile
/payment_profile/getRetrieve the status of a Payment Profile
/transfer/originator/createCreate a new originator
/transfer/originator/getGet the status of an originator's onboarding
/transfer/originator/listGet the status of all originators' onboarding
/transfer/questionnaire/createGenerate a Plaid-hosted onboarding UI URL
See also
/sandbox/payment_profile/reset_loginSimulate a Payment Profile login invalidation
/sandbox/transfer/simulateSimulate a transfer event (Sandbox only)
/sandbox/transfer/sweep/simulateSimulate creating a sweep (Sandbox only)
/sandbox/transfer/fire_webhookSimulate a transfer webhook (Sandbox only)
Webhooks
TRANSFER_EVENTS_UPDATENew transfer events available

Endpoints

/transfer/authorization/create

Create a transfer authorization

Use the /transfer/authorization/create endpoint to determine transfer failure risk.
In Plaid's Sandbox environment the decisions will be returned as follows:
- To approve a transfer with null rationale code, make an authorization request with an amount less than the available balance in the account.
- To approve a transfer with the rationale code MANUALLY_VERIFIED_ITEM, create an Item in Link through the Same Day Micro-deposits flow.
- To approve a transfer with the rationale code ITEM_LOGIN_REQUIRED, reset the login for an Item.
- To decline a transfer with the rationale code NSF, the available balance on the account must be less than the authorization amount. See Create Sandbox test data for details on how to customize data in Sandbox.
- To decline a transfer with the rationale code RISK, the available balance on the account must be exactly $0. See Create Sandbox test data for details on how to customize data in Sandbox.
device.ip_address, device.user_agent are required fields.
For Guarantee, the following fields are required : idempotency_key, user.phone_number (optional if email_address provided), user.email_address (optional if phone_number provided), device.ip_address, device.user_agent, and user_present.

transfer/authorization/create

Request fields and example

client_id
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.
secret
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. Required if not using payment_profile_token.
account_id
string
The Plaid account_id for the account that will be debited or credited. Required if not using payment_profile_token.
payment_profile_token
string
The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using access_token.
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
network
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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, rtp
amount
requiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
ach_class
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.
legal_name
requiredstring
The user's legal name.
phone_number
string
The user's phone number. In order to qualify for a guaranteed transfer, at least one of phone_number or email_address must be provided.
email_address
string
The user's email address. In order to qualify for a guaranteed transfer, at least one of phone_number or email_address must be provided.
address
object
The address associated with the account holder. Providing this data will improve the likelihood that Plaid will be able to guarantee the transfer, if applicable.
street
string
The street number and name (i.e., "100 Market St.").
city
string
Ex. "San Francisco"
region
string
The state or province (e.g., "CA").
postal_code
string
The postal code (e.g., "94103").
country
string
A two-letter country code (e.g., "US").
device
object
Information about the device being used to initiate the authorization.
ip_address
string
The IP address of the device being used to initiate the authorization. Required for Guarantee.
user_agent
string
The user agent of the device being used to initiate the authorization. Required for Guarantee.
iso_currency_code
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. 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.
Failure to provide this key may result in duplicate charges.
Required for guaranteed ACH customers.

Max length: 50
user_present
boolean
Required for Guarantee. 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.
with_guarantee
boolean
If set to false, Plaid will not offer a guarantee_decision for this request(Guarantee customers only).

Default: true
beacon_session_id
string
The unique identifier returned by Plaid's beacon when it is run on your webpage. Required for Guarantee customers who are not using Transfer UI and have a web checkout experience.
originator_client_id
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).
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.
created
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
nullable object
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. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
description
string
A human-readable description of the code associated with a transfer approval or transfer decline.
guarantee_decision
nullable string
Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either GUARANTEED or NOT_GUARANTEED indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale field. Refer to the code field in guarantee_decision_rationale for details.

Possible values: GUARANTEED, NOT_GUARANTEED, null
guarantee_decision_rationale
nullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
code
string
A code representing the reason Plaid declined to guarantee this transfer:
RETURN_BANK: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.
RETURN_CUSTOMER: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.
GUARANTEE_LIMIT_REACHED: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.
RISK_ESTIMATE_UNAVAILABLE: A risk estimate is unavailable for this Item.
REQUIRED_PARAM_MISSING: Required fields are missing.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE, REQUIRED_PARAM_MISSING
description
string
A human-readable description of why the transfer cannot be guaranteed.
proposed_transfer
object
Details regarding the proposed transfer.
ach_class
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
account_id
string
The Plaid account_id for the account that will be debited or credited.
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
network
string
The network or rails used for the transfer.
origination_account_id
string
Plaid's unique identifier for the origination account that was used for this transfer.
iso_currency_code
string
The currency of the transfer amount. The default value is "USD".
originator_client_id
nullable string
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).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "authorization": {
3    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "created": "2020-08-06T17:27:15Z",
5    "decision": "approved",
6    "decision_rationale": null,
7    "guarantee_decision": "GUARANTEED",
8    "guarantee_decision_rationale": null,
9    "proposed_transfer": {
10      "ach_class": "ppd",
11      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12      "type": "credit",
13      "user": {
14        "legal_name": "Anne Charleston",
15        "phone_number": "510-555-0128",
16        "email_address": "acharleston@email.com",
17        "address": {
18          "street": "123 Main St.",
19          "city": "San Francisco",
20          "region": "CA",
21          "postal_code": "94053",
22          "country": "US"
23        }
24      },
25      "amount": "12.34",
26      "network": "ach",
27      "iso_currency_code": "USD",
28      "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
29      "originator_client_id": null
30    }
31  },
32  "request_id": "saKrIBuEB9qJZno"
33}

/transfer/create

Create a transfer

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

transfer/create

Request fields and example

client_id
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.
secret
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. Required if not using payment_profile_token.
account_id
string
The Plaid account_id for the account that will be debited or credited. Required if not using payment_profile_token.
payment_profile_token
string
The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using access_token.
authorization_id
requiredstring
Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
requiredstring
The transfer description. Maximum of 10 characters.

Max length: 10
metadata
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
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.
ach_class
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
account_id
string
The account ID that should be credited/debited for this transfer.
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
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
nullable string
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
network
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullable object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullable string
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.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullable 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
origination_account_id
string
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decision
nullable string
Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either GUARANTEED or NOT_GUARANTEED indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale field. Refer to the code field in guarantee_decision_rationale for details.

Possible values: GUARANTEED, NOT_GUARANTEED, null
guarantee_decision_rationale
nullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
code
string
A code representing the reason Plaid declined to guarantee this transfer:
RETURN_BANK: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.
RETURN_CUSTOMER: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.
GUARANTEE_LIMIT_REACHED: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.
RISK_ESTIMATE_UNAVAILABLE: A risk estimate is unavailable for this Item.
REQUIRED_PARAM_MISSING: Required fields are missing.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE, REQUIRED_PARAM_MISSING
description
string
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullable string
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
unauthorized_return_window
nullable string
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
originator_client_id
nullable string
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.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
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. cancelled: The refund was cancelled by the client. failed: The refund failed or was returned.

Possible values: pending, posted, cancelled, failed
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer": {
3    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
4    "ach_class": "ppd",
5    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
6    "type": "credit",
7    "user": {
8      "legal_name": "Anne Charleston",
9      "phone_number": "510-555-0128",
10      "email_address": "acharleston@email.com",
11      "address": {
12        "street": "123 Main St.",
13        "city": "San Francisco",
14        "region": "CA",
15        "postal_code": "94053",
16        "country": "US"
17      }
18    },
19    "amount": "12.34",
20    "description": "payment",
21    "created": "2020-08-06T17:27:15Z",
22    "refunds": [],
23    "status": "pending",
24    "network": "ach",
25    "cancellable": true,
26    "guarantee_decision": "GUARANTEED",
27    "guarantee_decision_rationale": null,
28    "failure_reason": null,
29    "metadata": {
30      "key1": "value1",
31      "key2": "value2"
32    },
33    "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
34    "iso_currency_code": "USD",
35    "standard_return_window": "2020-08-07",
36    "unauthorized_return_window": "2020-10-07",
37    "originator_client_id": "569ed2f36b3a3a021713abc1"
38  },
39  "request_id": "saKrIBuEB9qJZno"
40}

/transfer/cancel

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

client_id
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.
secret
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_id
requiredstring
Plaid’s unique identifier for a transfer.
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

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "saKrIBuEB9qJZno"
3}

/transfer/get

Retrieve a transfer

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

transfer/get

Request fields and example

client_id
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.
secret
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_id
requiredstring
Plaid’s unique identifier for a transfer.
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.
ach_class
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
account_id
string
The account ID that should be credited/debited for this transfer.
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
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
nullable string
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
network
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullable object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullable string
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.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullable 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
origination_account_id
string
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decision
nullable string
Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either GUARANTEED or NOT_GUARANTEED indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale field. Refer to the code field in guarantee_decision_rationale for details.

Possible values: GUARANTEED, NOT_GUARANTEED, null
guarantee_decision_rationale
nullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
code
string
A code representing the reason Plaid declined to guarantee this transfer:
RETURN_BANK: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.
RETURN_CUSTOMER: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.
GUARANTEE_LIMIT_REACHED: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.
RISK_ESTIMATE_UNAVAILABLE: A risk estimate is unavailable for this Item.
REQUIRED_PARAM_MISSING: Required fields are missing.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE, REQUIRED_PARAM_MISSING
description
string
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullable string
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
unauthorized_return_window
nullable string
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
originator_client_id
nullable string
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.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
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. cancelled: The refund was cancelled by the client. failed: The refund failed or was returned.

Possible values: pending, posted, cancelled, failed
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "cancellable": true,
7    "created": "2020-08-06T17:27:15Z",
8    "description": "Desc",
9    "guarantee_decision": null,
10    "guarantee_decision_rationale": null,
11    "failure_reason": {
12      "ach_return_code": "R13",
13      "description": "Invalid ACH routing number"
14    },
15    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
16    "metadata": {
17      "key1": "value1",
18      "key2": "value2"
19    },
20    "network": "ach",
21    "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
22    "originator_client_id": null,
23    "refunds": [],
24    "status": "pending",
25    "type": "credit",
26    "iso_currency_code": "USD",
27    "standard_return_window": "2020-08-07",
28    "unauthorized_return_window": "2020-10-07",
29    "user": {
30      "email_address": "acharleston@email.com",
31      "legal_name": "Anne Charleston",
32      "phone_number": "510-555-0128",
33      "address": {
34        "street": "123 Main St.",
35        "city": "San Francisco",
36        "region": "CA",
37        "postal_code": "94053",
38        "country": "US"
39      }
40    }
41  },
42  "request_id": "saKrIBuEB9qJZno"
43}

/transfer/list

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

client_id
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.
secret
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
count
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
origination_account_id
string
Filter transfers to only those originated through the specified origination account.
originator_client_id
string
Filter transfers to only those with the specified originator client.
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.
ach_class
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
account_id
string
The account ID that should be credited/debited for this transfer.
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
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
nullable string
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
network
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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, rtp
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullable object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullable string
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.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullable 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
origination_account_id
string
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decision
nullable string
Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either GUARANTEED or NOT_GUARANTEED indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale field. Refer to the code field in guarantee_decision_rationale for details.

Possible values: GUARANTEED, NOT_GUARANTEED, null
guarantee_decision_rationale
nullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
code
string
A code representing the reason Plaid declined to guarantee this transfer:
RETURN_BANK: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.
RETURN_CUSTOMER: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.
GUARANTEE_LIMIT_REACHED: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.
RISK_ESTIMATE_UNAVAILABLE: A risk estimate is unavailable for this Item.
REQUIRED_PARAM_MISSING: Required fields are missing.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE, REQUIRED_PARAM_MISSING
description
string
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullable string
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
unauthorized_return_window
nullable string
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
originator_client_id
nullable string
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.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
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. cancelled: The refund was cancelled by the client. failed: The refund failed or was returned.

Possible values: pending, posted, cancelled, failed
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfers": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "ach_class": "ppd",
6      "amount": "12.34",
7      "cancellable": true,
8      "created": "2019-12-09T17:27:15Z",
9      "description": "Desc",
10      "guarantee_decision": null,
11      "guarantee_decision_rationale": null,
12      "failure_reason": {
13        "ach_return_code": "R13",
14        "description": "Invalid ACH routing number"
15      },
16      "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
17      "metadata": {
18        "key1": "value1",
19        "key2": "value2"
20      },
21      "network": "ach",
22      "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
23      "originator_client_id": null,
24      "refunds": [],
25      "status": "pending",
26      "type": "credit",
27      "iso_currency_code": "USD",
28      "standard_return_window": "2020-08-07",
29      "unauthorized_return_window": "2020-10-07",
30      "user": {
31        "email_address": "acharleston@email.com",
32        "legal_name": "Anne Charleston",
33        "phone_number": "510-555-0128",
34        "address": {
35          "street": "123 Main St.",
36          "city": "San Francisco",
37          "region": "CA",
38          "postal_code": "94053",
39          "country": "US"
40        }
41      }
42    }
43  ],
44  "request_id": "saKrIBuEB9qJZno"
45}

/transfer/event/list

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

client_id
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.
secret
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
transfer_id
string
Plaid’s unique identifier for a transfer.
account_id
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_id
string
Plaid’s unique identifier for a sweep.
count
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
origination_account_id
string
The origination account ID to get events for transfers from a specific origination account.
originator_client_id
string
Filter transfer events to only those with the specified originator client.
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.
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.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept
account_id
string
The account ID associated with the transfer.
transfer_id
string
Plaid’s unique identifier for a transfer.
origination_account_id
nullable string
The ID of the origination account that this balance belongs to.
transfer_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
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reason
nullable object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullable string
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.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullable string
Plaid’s unique identifier for a sweep.
sweep_amount
nullable string
A signed amount of how much was swept or return_swept (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullable string
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullable string
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).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "transfer_amount": "12.34",
6      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "transfer_type": "credit",
8      "event_id": 1,
9      "event_type": "posted",
10      "failure_reason": null,
11      "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
12      "originator_client_id": "569ed2f36b3a3a021713abc1",
13      "refund_id": null,
14      "sweep_amount": null,
15      "sweep_id": null,
16      "timestamp": "2019-12-09T17:27:15Z"
17    }
18  ],
19  "request_id": "mdqfuVxeoza6mhu"
20}

/transfer/event/sync

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

client_id
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.
secret
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
count
integer
The maximum number of transfer events to return.

Default: 25
Minimum: 1
Maximum: 25 
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.
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.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept
account_id
string
The account ID associated with the transfer.
transfer_id
string
Plaid’s unique identifier for a transfer.
origination_account_id
nullable string
The ID of the origination account that this balance belongs to.
transfer_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
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reason
nullable object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullable string
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.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullable string
Plaid’s unique identifier for a sweep.
sweep_amount
nullable string
A signed amount of how much was swept or return_swept (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullable string
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullable string
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).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "transfer_amount": "12.34",
6      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "transfer_type": "credit",
8      "event_id": 1,
9      "event_type": "pending",
10      "failure_reason": null,
11      "origination_account_id": null,
12      "originator_client_id": null,
13      "refund_id": null,
14      "sweep_amount": null,
15      "sweep_id": null,
16      "timestamp": "2019-12-09T17:27:15Z"
17    }
18  ],
19  "request_id": "mdqfuVxeoza6mhu"
20}

/transfer/sweep/get

Retrieve a sweep

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

transfer/sweep/get

Request fields and example

client_id
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.
secret
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.
sweep_id
requiredstring
Plaid’s unique identifier for a sweep.
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.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
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.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullable string
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweep": {
3    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
4    "created": "2020-08-06T17:27:15Z",
5    "amount": "12.34",
6    "iso_currency_code": "USD",
7    "settled": "2020-08-07"
8  },
9  "request_id": "saKrIBuEB9qJZno"
10}

/transfer/sweep/list

List sweeps

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

transfer/sweep/list

Request fields and example

client_id
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.
secret
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
count
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
originator_client_id
string
Filter sweeps to only those with the specified originator client.
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.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
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.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullable string
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweeps": [
3    {
4      "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
5      "created": "2019-12-09T17:27:15Z",
6      "amount": "-12.34",
7      "iso_currency_code": "USD",
8      "settled": "2019-12-10",
9      "originator_client_id": null
10    }
11  ],
12  "request_id": "saKrIBuEB9qJZno"
13}

/transfer/intent/create

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

client_id
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.
secret
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.
account_id
string
The Plaid account_id for the account that will be debited or credited.
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
amount
requiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
description
requiredstring
A description for the underlying transfer. Maximum of 8 characters.

Min length: 1
Max length: 8
ach_class
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
origination_account_id
string
Plaid’s unique identifier for the origination account for the intent. If not provided, the default account will be used.
user
requiredobject
The legal name and other information for the account holder.
legal_name
requiredstring
The user's legal name.
phone_number
string
The user's phone number.
email_address
string
The user's email address.
address
object
The address associated with the account holder. Providing this data will improve the likelihood that Plaid will be able to guarantee the transfer, if applicable.
street
string
The street number and name (i.e., "100 Market St.").
city
string
Ex. "San Francisco"
region
string
The state or province (e.g., "CA").
postal_code
string
The postal code (e.g., "94103").
country
string
A two-letter country code (e.g., "US").
metadata
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
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
require_guarantee
boolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guarantee customers only).

Default: false 
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.
created
string
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
status
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
account_id
nullable string
The Plaid account_id for the account that will be debited or credited. Returned only if account_id was set on intent creation.
origination_account_id
string
Plaid’s unique identifier for the origination account for the intent. If not provided, the default account will be used.
amount
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
ach_class
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
description
string
A description for the underlying transfer. Maximum of 8 characters.
metadata
nullable 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
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
require_guarantee
nullable boolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guarantee customers only).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "iso_currency_code": "USD",
7    "created": "2020-08-06T17:27:15Z",
8    "description": "Desc",
9    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
10    "metadata": {
11      "key1": "value1",
12      "key2": "value2"
13    },
14    "mode": "PAYMENT",
15    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
16    "status": "PENDING",
17    "user": {
18      "address": {
19        "street": "100 Market Street",
20        "city": "San Francisco",
21        "region": "CA",
22        "postal_code": "94103",
23        "country": "US"
24      },
25      "email_address": "acharleston@email.com",
26      "legal_name": "Anne Charleston",
27      "phone_number": "123-456-7890"
28    }
29  },
30  "request_id": "saKrIBuEB9qJZno"
31}

/transfer/intent/get

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

client_id
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.
secret
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.
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.
created
string
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
status
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
transfer_id
nullable string
Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise.
failure_reason
nullable object
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
nullable 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
authorization_decision_rationale
nullable object
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. Possible values are:
MANUALLY_VERIFIED_ITEM – Item created via same-day micro deposits, limited information available. Plaid will offer approved as a transaction decision.
ITEM_LOGIN_REQUIRED – Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved as a transaction decision.
PAYMENT_PROFILE_LOGIN_REQUIRED - Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved as a transaction decision.
ERROR – Unable to collect the account information due to an error. Plaid will offer approved as a transaction decision.
NSF – Transaction likely to result in a return due to insufficient funds. Plaid will offer declined as a transaction decision.
RISK - Transaction is high-risk. Plaid will offer declined as a transaction decision.
TRANSFER_LIMIT_REACHED - One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined as a transaction decision.
MIGRATED_ACCOUNT_ITEM - Item created via /transfer/account_migration endpoint, limited information available. Plaid will offer approved as a transaction decision.

Possible values: NSF, RISK, TRANSFER_LIMIT_REACHED, MANUALLY_VERIFIED_ITEM, ITEM_LOGIN_REQUIRED, PAYMENT_PROFILE_LOGIN_REQUIRED, ERROR, MIGRATED_ACCOUNT_ITEM
description
string
A human-readable description of the code associated with a transfer approval or transfer decline.
account_id
nullable string
The Plaid account_id for the account that will be debited or credited. Returned only if account_id was set on intent creation.
origination_account_id
string
Plaid’s unique identifier for the origination account used for the transfer.
amount
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
ach_class
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.
legal_name
string
The user's legal name.
phone_number
nullable string
The user's phone number.
email_address
nullable string
The user's email address.
address
nullable object
The address associated with the account holder.
street
nullable string
The street number and name (i.e., "100 Market St.").
city
nullable string
Ex. "San Francisco"
region
nullable string
The state or province (e.g., "CA").
postal_code
nullable string
The postal code (e.g., "94103").
country
nullable string
A two-letter country code (e.g., "US").
description
string
A description for the underlying transfer. Maximum of 8 characters.
metadata
nullable 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
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
require_guarantee
nullable boolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guarantee customers only).
guarantee_decision
nullable string
Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either GUARANTEED or NOT_GUARANTEED indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale field. Refer to the code field in guarantee_decision_rationale for details.

Possible values: GUARANTEED, NOT_GUARANTEED, null
guarantee_decision_rationale
nullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
code
string
A code representing the reason Plaid declined to guarantee this transfer:
RETURN_BANK: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.
RETURN_CUSTOMER: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.
GUARANTEE_LIMIT_REACHED: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.
RISK_ESTIMATE_UNAVAILABLE: A risk estimate is unavailable for this Item.
REQUIRED_PARAM_MISSING: Required fields are missing.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE, REQUIRED_PARAM_MISSING
description
string
A human-readable description of why the transfer cannot be guaranteed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_intent": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "iso_currency_code": "USD",
7    "authorization_decision": "APPROVED",
8    "authorization_decision_rationale": null,
9    "created": "2019-12-09T17:27:15Z",
10    "description": "Desc",
11    "failure_reason": null,
12    "guarantee_decision": null,
13    "guarantee_decision_rationale": null,
14    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
15    "metadata": {
16      "key1": "value1",
17      "key2": "value2"
18    },
19    "mode": "DISBURSEMENT",
20    "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",
21    "status": "SUCCEEDED",
22    "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2",
23    "user": {
24      "address": {
25        "street": "123 Main St.",
26        "city": "San Francisco",
27        "region": "California",
28        "postal_code": "94053",
29        "country": "US"
30      },
31      "email_address": "acharleston@email.com",
32      "legal_name": "Anne Charleston",
33      "phone_number": "510-555-0128"
34    }
35  },
36  "request_id": "saKrIBuEB9qJZno"
37}

/transfer/refund/create

Create a refund

Use the /transfer/refund/create endpoint to create a refund for a transfer. A transfer can be refunded if the transfer was initiated in the past 180 days.
Processing of the refund will not occur until at least 3 business days following the transfer's settlement date, plus any hold/settlement delays. This 3-day window helps better protect your business from regular ACH returns. Consumer initiated returns (unauthorized returns) could still happen for about 60 days from the settlement date. If the original transfer is canceled, returned or failed, all pending refunds will automatically be canceled. Processed refunds cannot be revoked.

transfer/refund/create

Request fields and example

client_id
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.
secret
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_id
requiredstring
The ID of the transfer to refund.
amount
requiredstring
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
idempotency_key
requiredstring
A random key provided by the client, per unique refund. Maximum of 50 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a refund fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single refund is created.

Max length: 50 
1const request: TransferRefundCreateRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3  amount: '12.34',
4  idempotency_key: 'VEK2ea3X6LKywsc8J6pg',
5};
6
7try {
8  const response = await client.transferRefundCreate(request);
9} catch (error) {
10  // handle error
11}
transfer/refund/create

Response fields and example

refund
object
Represents a refund within the Transfers API.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
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. cancelled: The refund was cancelled by the client. failed: The refund failed or was returned.

Possible values: pending, posted, cancelled, failed
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "refund": {
3    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
4    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5    "amount": "12.34",
6    "status": "pending",
7    "created": "2020-08-06T17:27:15Z"
8  },
9  "request_id": "saKrIBuEB9qJZno"
10}

/transfer/refund/cancel

Cancel a refund

Use the /transfer/refund/cancel endpoint to cancel a refund. A refund is eligible for cancellation if it has not yet been submitted to the payment network.

transfer/refund/cancel

Request fields and example

client_id
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.
secret
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.
refund_id
requiredstring
Plaid’s unique identifier for a refund.
1const request: TransferRefundCancelRequest = {
2  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRefundCancel(request);
7} catch (error) {
8  // handle error
9}
transfer/refund/cancel

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "saKrIBuEB9qJZno"
3}

/transfer/refund/get

Retrieve a refund

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

transfer/refund/get

Request fields and example

client_id
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.
secret
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.
refund_id
requiredstring
Plaid’s unique identifier for a refund.
1const request: TransferRefundGetRequest = {
2  refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4
5try {
6  const response = await client.transferRefundGet(request);
7} catch (error) {
8  // handle error
9}
transfer/refund/get

Response fields and example

refund
object
Represents a refund within the Transfers API.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
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. cancelled: The refund was cancelled by the client. failed: The refund failed or was returned.

Possible values: pending, posted, cancelled, failed
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "refund": {
3    "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",
4    "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
5    "amount": "12.34",
6    "status": "pending",
7    "created": "2020-08-06T17:27:15Z"
8  },
9  "request_id": "saKrIBuEB9qJZno"
10}

/transfer/migrate_account

Migrate account into Transfers

As an alternative to adding Items via Link, you can also use the /transfer/migrate_account endpoint to migrate known account and routing numbers to Plaid Items. Note that Items created in this way are not compatible with endpoints for other products, such as /accounts/balance/get, and can only be used with Transfer endpoints. If you require access to other endpoints, create the Item through Link instead. Access to /transfer/migrate_account is not enabled by default; to obtain access, contact your Plaid Account Manager.

transfer/migrate_account

Request fields and example

client_id
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.
secret
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.
account_number
requiredstring
The user's account number.
routing_number
requiredstring
The user's routing number.
wire_routing_number
string
The user's wire transfer routing number. This is the ABA number; for some institutions, this may differ from the ACH number used in routing_number.
account_type
requiredstring
The type of the bank account (checking or savings).
1const request: TransferMigrateAccountRequest = {
2  account_number: '100000000',
3  routing_number: '121122676',
4  account_type: 'checking',
5};
6try {
7  const response = await plaidClient.transferMigrateAccount(request);
8  const access_token = response.data.access_token;
9} catch (error) {
10  // handle error
11}
transfer/migrate_account

Response fields and example

access_token
string
The Plaid access_token for the newly created Item.
account_id
string
The Plaid account_id for the newly created Item.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0",
3  "account_id": "zvyDgbeeDluZ43AJP6m5fAxDlgoZXDuoy5gjN",
4  "request_id": "mdqfuVxeoza6mhu"
5}

/payment_profile/create

Create payment profile

Use /payment_profile/create endpoint to create a new payment profile. To initiate the account linking experience, call /link/token/create and provide the payment_profile_token in the transfer.payment_profile_token field. You can then use the payment_profile_token when creating transfers using /transfer/authorization/create and /transfer/create.

payment_profile/create

Request fields and example

client_id
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.
secret
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.
1const request: PaymentProfileCreateRequest = {};
2
3try {
4  const response = await client.paymentProfileCreateRequest(request);
5  const paymentProfileToken = response.data.payment_profile_token;
6} catch (error) {
7  // handle error
8}
payment_profile/create

Response fields and example

payment_profile_token
string
A payment profile token associated with the Payment Profile data that is being requested.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "payment_profile_token": "payment-profile-sandbox-eda0b25e-8ef3-4ebb-9ef7-1ef3db3c5ee8",
3  "request_id": "4ciYmmesdqSiUAB"
4}

/payment_profile/remove

Remove payment profile

Use the /payment_profile/remove endpoint to remove a given Payment Profile. Once it’s removed, it can no longer be used to create transfers.

payment_profile/remove

Request fields and example

client_id
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.
secret
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.
payment_profile_token
requiredstring
A payment profile token associated with the Payment Profile data that is being requested.
1const request: PaymentProfileRemoveRequest = {
2  payment_profile_token:
3    'payment-profile-sandbox-8b66ac67-b9ee-4084-9f72-ceb4ffb2e914',
4};
5
6try {
7  const response = await client.paymentProfileRemoveRequest(request);
8} catch (error) {
9  // handle error
10}
payment_profile/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "4ciYmmesdqSiUAB"
3}

/payment_profile/get

Get payment profile

Use /payment_profile/get endpoint to get the status of a given Payment Profile.

payment_profile/get

Request fields and example

client_id
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.
secret
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.
payment_profile_token
requiredstring
A payment profile token associated with the Payment Profile data that is being requested.
1const request: PaymentProfileGetRequest = {
2  payment_profile_token:
3    'payment-profile-sandbox-8b66ac67-b9ee-4084-9f72-ceb4ffb2e914',
4};
5
6try {
7  const response = await client.paymentProfileGetRequest(request);
8  const status = response.data.status;
9} catch (error) {
10  // handle error
11}
payment_profile/get

Response fields and example

updated_at
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time the given Payment Profile was updated at

Format: date-time
created_at
string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the time the given Payment Profile was created at

Format: date-time
deleted_at
nullable string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the time the given Payment Profile was deleted at. Always null if the Payment Profile has not been deleted

Format: date-time
status
string
The status of the given Payment Profile.
READY: This Payment Profile is ready to be used to create transfers using /transfer/authorization/create and /transfer/create.
PENDING: This Payment Profile is not ready to be used. You’ll need to call /link/token/create and provide the payment_profile_token in the transfer.payment_profile_token field to initiate the account linking experience.
REMOVED: This Payment Profile has been removed.

Possible values: PENDING, READY, REMOVED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "status": "READY",
3  "updated_at": "2022-07-07T12:48:37Z",
4  "created_at": "2022-07-05T12:48:37Z",
5  "deleted_at": null,
6  "request_id": "4ciYmmesdqSiUAB"
7}

/transfer/originator/create

Create a new originator

Use the /transfer/originator/create endpoint to create a new originator and return an originator_client_id.

transfer/originator/create

Request fields and example

client_id
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.
secret
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.
company_name
requiredstring
The company name of the end customer being created. This will be displayed in public-facing surfaces, e.g. Plaid Dashboard.
1const request: TransferOriginatorCreateRequest = {
2  company_name: 'Marketplace of Shannon',
3};
4
5try {
6  const response = await client.transferOriginatorCreate(request);
7} catch (error) {
8  // handle error
9}
transfer/originator/create

Response fields and example

originator_client_id
string
Client ID of the originator. This identifier will be used when creating transfers and should be stored associated with end user information.
company_name
string
The company name of the end customer.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "originator_client_id": "6a65dh3d1h0d1027121ak184",
3  "company_name": "Marketplace of Shannon",
4  "request_id": "4zlKapIkTm8p5KM"
5}

/transfer/originator/get

Get status of an originator's onboarding

The /transfer/originator/get endpoint gets status updates for an originator's onboarding process. This information is also available via the Transfer page on the Plaid dashboard.

transfer/originator/get

Request fields and example

client_id
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.
secret
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.
originator_client_id
requiredstring
Client ID of the end customer (i.e. the originator).
1const request: TransferOriginatorGetRequest = {
2  originator_client_id: '6a65dh3d1h0d1027121ak184',
3};
4
5try {
6  const response = await client.transferOriginatorGet(request);
7} catch (error) {
8  // handle error
9}
transfer/originator/get

Response fields and example

originator
object
Originator and their status.
client_id
string
Originator’s client ID.
transfer_diligence_status
string
Originator’s diligence status.

Possible values: under_review, approved, denied
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "originator": {
3    "client_id": "6a65dh3d1h0d1027121ak184",
4    "transfer_diligence_status": "approved"
5  },
6  "request_id": "saKrIBuEB9qJZno"
7}

/transfer/originator/list

Get status of all originators' onboarding

The /transfer/originator/list endpoint gets status updates for all of your originators' onboarding. This information is also available via the Plaid dashboard.

transfer/originator/list

Request fields and example

client_id
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.
secret
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.
count
integer
The maximum number of originators to return.

Maximum: 25
Minimum: 1
Default: 25
offset
integer
The number of originators to skip before returning results.

Minimum: 0
Default: 0 
1const request: TransferOriginatorListRequest = {
2  count: 14,
3  offset: 2,
4};
5
6try {
7  const response = await client.transferOriginatorList(request);
8} catch (error) {
9  // handle error
10}
transfer/originator/list