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/repayment/listRetrieve a list of repayments (Guarantee only)
/transfer/repayment/return/listRetrieve a list of returns included in a repayment (Guarantee only)
/transfer/intent/createCreate a transfer intent and invoke Transfer UI (Transfer UI only)
/transfer/intent/getRetrieve information about a transfer intent (Transfer UI only)
See also
/sandbox/transfer/simulateSimulate a transfer event (Sandbox only)
/sandbox/transfer/sweep/simulateSimulate creating a sweep (Sandbox only)
/sandbox/transfer/repayment/simulateTrigger the creation of a repayment (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 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.

transfer/authorization/create

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokenrequiredstring
The Plaid access_token for the account that will be debited or credited.
account_idrequiredstring
The Plaid account_id for the account that will be debited or credited.
typerequiredstring
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
networkrequiredstring
The network or rails used for the transfer. Valid options are ach or same-day-ach.

Possible values: ach, same-day-ach
amountrequiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
ach_classrequiredstring
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
userrequiredobject
The legal name and other information for the account holder.
legal_namerequiredstring
The user's legal name.
phone_numberstring
The user's phone number.
email_addressstring
The user's email address.
addressobject
The address associated with the account holder.
streetstring
The street number and name (i.e., "100 Market St.").
citystring
Ex. "San Francisco"
regionstring
The state or province (e.g., "CA").
postal_codestring
The postal code (e.g., "94103").
countrystring
A two-letter country code (e.g., "US").
deviceobject
Information about the device being used to initiate the authorization.
ip_addressstring
The IP address of the device being used to initiate the authorization.
user_agentstring
The user agent of the device being used to initiate the authorization.
origination_account_idstring
Plaid's unique identifier for the origination account for this authorization. If not specified, the default account will be used.
iso_currency_codestring
The currency of the transfer amount. The default value is "USD".
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

authorizationobject
Contains the authorization decision for a proposed transfer
idstring
Plaid’s unique identifier for a transfer authorization.
createdstring
The datetime representing when the authorization was created, in the format 2006-01-02T15:04:05Z.

Format: date-time
decisionstring
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 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_rationalenullable 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.
codestring
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.
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.
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.

Possible values: NSF, RISK, MANUALLY_VERIFIED_ITEM, LOGIN_REQUIRED, ERROR
descriptionstring
A human-readable description of the code associated with a transfer approval or transfer decline.
guarantee_decisionnullable string
Indicates whether the transfer is guaranteed by Plaid (Guaranteed ACH 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_rationalenullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
codestring
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 Guaranteed ACH 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.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE
descriptionstring
A human-readable description of why the transfer cannot be guaranteed.
proposed_transferobject
Details regarding the proposed transfer.
ach_classstring
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_idstring
The Plaid account_id for the account that will be debited or credited.
typestring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
networkstring
The network or rails used for the transfer.
origination_account_idstring
Plaid's unique identifier for the origination account that was used for this transfer.
iso_currency_codestring
The currency of the transfer amount. The default value is "USD".
request_idstring
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    }
30  },
31  "request_id": "saKrIBuEB9qJZno"
32}

/transfer/create

Create a transfer

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

transfer/create

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
idempotency_keydeprecatedstring
Deprecated. authorization_id is now used as idempotency instead.
A random key provided by the client, per unique transfer. Maximum of 50 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transfer fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single transfer is created.

Max length: 50
access_tokenrequiredstring
The Plaid access_token for the account that will be debited or credited.
account_idrequiredstring
The Plaid account_id for the account that will be debited or credited.
authorization_idrequiredstring
Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.
typerequiredstring
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
networkrequiredstring
The network or rails used for the transfer. Valid options are ach or same-day-ach.

Possible values: ach, same-day-ach
amountrequiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
descriptionrequiredstring
The transfer description. Maximum of 10 characters.

Max length: 10
ach_classrequiredstring
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
userrequiredobject
The legal name and other information for the account holder.
legal_namerequiredstring
The user's legal name.
phone_numberstring
The user's phone number.
email_addressstring
The user's email address.
addressobject
The address associated with the account holder.
streetstring
The street number and name (i.e., "100 Market St.").
citystring
Ex. "San Francisco"
regionstring
The state or province (e.g., "CA").
postal_codestring
The postal code (e.g., "94103").
countrystring
A two-letter country code (e.g., "US").
metadataobject
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_idstring
Plaid’s unique identifier for the origination account for this transfer. If you have more than one origination account, this value must be specified. Otherwise, this field should be left blank.
iso_currency_codestring
The currency of the transfer amount. The default value is "USD".
1const request: TransferCreateRequest = {
2  type: 'credit',
3  network: 'ach',
4  amount: '12.34',
5  description: 'payment',
6  ach_class: 'ppd',
7  user: {
8    legal_name: 'Anne Charleston',
9  },
10  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
11  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
12  authorization_id: '231h012308h3101z21909sw',
13};
14try {
15  const response = await client.transferCreate(request);
16  const transfer = response.data.transfer;
17} catch (error) {
18  // handle error
19}
transfer/create

Response fields and example

transferobject
Represents a transfer within the Transfers API.
idstring
Plaid’s unique identifier for a transfer.
ach_classstring
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_idstring
The account ID that should be credited/debited for this transfer.
typestring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
descriptionstring
The description of the transfer.
createdstring
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
statusstring
The status of the transfer.

Possible values: pending, posted, cancelled, failed, reversed
sweep_statusnullable 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. reverse_swept: The transfer was reversed, 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 reversed before being swept)

Possible values: null, unswept, swept, reverse_swept
networkstring
The network or rails used for the transfer. Valid options are ach or same-day-ach.

Possible values: ach, same-day-ach
cancellableboolean
When true, you can still cancel this transfer.
failure_reasonnullable object
The failure reason if the event type for a transfer is "failed" or "reversed". Null value otherwise.
ach_return_codenullable string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Transfer errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
metadatanullable 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_idstring
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decisionnullable string
Indicates whether the transfer is guaranteed by Plaid (Guaranteed ACH 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_rationalenullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
codestring
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 Guaranteed ACH 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.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE
descriptionstring
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_codestring
The currency of the transfer amount, e.g. "USD"
request_idstring
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    "status": "pending",
23    "network": "ach",
24    "cancellable": true,
25    "guarantee_decision": "GUARANTEED",
26    "guarantee_decision_rationale": null,
27    "failure_reason": null,
28    "metadata": {
29      "key1": "value1",
30      "key2": "value2"
31    },
32    "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
33    "iso_currency_code": "USD"
34  },
35  "request_id": "saKrIBuEB9qJZno"
36}

/transfer/cancel

Cancel a transfer

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

transfer/cancel

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_idrequiredstring
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_idstring
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 fetches information about the transfer corresponding to the given transfer_id.

transfer/get

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_idrequiredstring
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

transferobject
Represents a transfer within the Transfers API.
idstring
Plaid’s unique identifier for a transfer.
ach_classstring
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_idstring
The account ID that should be credited/debited for this transfer.
typestring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
descriptionstring
The description of the transfer.
createdstring
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
statusstring
The status of the transfer.

Possible values: pending, posted, cancelled, failed, reversed
sweep_statusnullable 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. reverse_swept: The transfer was reversed, 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 reversed before being swept)

Possible values: null, unswept, swept, reverse_swept
networkstring
The network or rails used for the transfer. Valid options are ach or same-day-ach.

Possible values: ach, same-day-ach
cancellableboolean
When true, you can still cancel this transfer.
failure_reasonnullable object
The failure reason if the event type for a transfer is "failed" or "reversed". Null value otherwise.
ach_return_codenullable string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Transfer errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
metadatanullable 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_idstring
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decisionnullable string
Indicates whether the transfer is guaranteed by Plaid (Guaranteed ACH 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_rationalenullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
codestring
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 Guaranteed ACH 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.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE
descriptionstring
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_codestring
The currency of the transfer amount, e.g. "USD"
request_idstring
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    "status": "pending",
23    "type": "credit",
24    "iso_currency_code": "USD",
25    "user": {
26      "email_address": "acharleston@email.com",
27      "legal_name": "Anne Charleston",
28      "phone_number": "510-555-0128",
29      "address": {
30        "street": "123 Main St.",
31        "city": "San Francisco",
32        "region": "CA",
33        "postal_code": "94053",
34        "country": "US"
35      }
36    }
37  },
38  "request_id": "saKrIBuEB9qJZno"
39}

/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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_datestring
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_datestring
The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
countinteger
The maximum number of transfers to return.

Minimum: 1
Maximum: 25
Default: 25
offsetinteger
The number of transfers to skip before returning results.

Default: 0
Minimum: 0
origination_account_idstring
Filter transfers to only those originated through the specified origination account.
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]
idstring
Plaid’s unique identifier for a transfer.
ach_classstring
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_idstring
The account ID that should be credited/debited for this transfer.
typestring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
descriptionstring
The description of the transfer.
createdstring
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
statusstring
The status of the transfer.

Possible values: pending, posted, cancelled, failed, reversed
sweep_statusnullable 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. reverse_swept: The transfer was reversed, 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 reversed before being swept)

Possible values: null, unswept, swept, reverse_swept
networkstring
The network or rails used for the transfer. Valid options are ach or same-day-ach.

Possible values: ach, same-day-ach
cancellableboolean
When true, you can still cancel this transfer.
failure_reasonnullable object
The failure reason if the event type for a transfer is "failed" or "reversed". Null value otherwise.
ach_return_codenullable string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Transfer errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
metadatanullable 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_idstring
Plaid’s unique identifier for the origination account that was used for this transfer.
guarantee_decisionnullable string
Indicates whether the transfer is guaranteed by Plaid (Guaranteed ACH 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_rationalenullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
codestring
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 Guaranteed ACH 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.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE
descriptionstring
A human-readable description of why the transfer cannot be guaranteed.
iso_currency_codestring
The currency of the transfer amount, e.g. "USD"
request_idstring
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      "status": "pending",
24      "type": "credit",
25      "iso_currency_code": "USD",
26      "user": {
27        "email_address": "acharleston@email.com",
28        "legal_name": "Anne Charleston",
29        "phone_number": "510-555-0128",
30        "address": {
31          "street": "123 Main St.",
32          "city": "San Francisco",
33          "region": "CA",
34          "postal_code": "94053",
35          "country": "US"
36        }
37      }
38    }
39  ],
40  "request_id": "saKrIBuEB9qJZno"
41}

/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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_datestring
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_datestring
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_idstring
Plaid’s unique identifier for a transfer.
account_idstring
The account ID to get events for all transactions to/from an account.
transfer_typestring
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, reversed, swept, reverse_swept
sweep_idstring
Plaid’s unique identifier for a sweep.
countinteger
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
offsetinteger
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 bank transfer events will be returned.

Default: 0
Minimum: 0
origination_account_idstring
The origination account ID to get events for transfers from a specific origination account.
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_idinteger
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

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

Format: date-time
event_typestring
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.
reversed: A posted transfer was reversed.
swept: The transfer was swept to / from the sweep account.
reverse_swept: Due to the transfer reversing, funds were pulled from or pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, reversed, swept, reverse_swept
account_idstring
The account ID associated with the transfer.
transfer_idstring
Plaid’s unique identifier for a transfer.
origination_account_idnullable string
The ID of the origination account that this balance belongs to.
transfer_typestring
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_amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reasonnullable object
The failure reason if the event type for a transfer is "failed" or "reversed". Null value otherwise.
ach_return_codenullable string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Transfer errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
sweep_idnullable string
Plaid’s unique identifier for a sweep.
sweep_amountnullable string
A signed amount of how much was swept or reverse_swept (decimal string with two digits of precision e.g. "-5.50").
request_idstring
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      "sweep_amount": null,
13      "sweep_id": null,
14      "timestamp": "2019-12-09T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}

/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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
after_idrequiredinteger
The latest (largest) event_id fetched via the sync endpoint, or 0 initially.

Minimum: 0
countinteger
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_idinteger
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

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

Format: date-time
event_typestring
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.
reversed: A posted transfer was reversed.
swept: The transfer was swept to / from the sweep account.
reverse_swept: Due to the transfer reversing, funds were pulled from or pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, reversed, swept, reverse_swept
account_idstring
The account ID associated with the transfer.
transfer_idstring
Plaid’s unique identifier for a transfer.
origination_account_idnullable string
The ID of the origination account that this balance belongs to.
transfer_typestring
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_amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
failure_reasonnullable object
The failure reason if the event type for a transfer is "failed" or "reversed". Null value otherwise.
ach_return_codenullable string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Transfer errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
sweep_idnullable string
Plaid’s unique identifier for a sweep.
sweep_amountnullable string
A signed amount of how much was swept or reverse_swept (decimal string with two digits of precision e.g. "-5.50").
request_idstring
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      "sweep_amount": null,
13      "sweep_id": null,
14      "timestamp": "2019-12-09T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}

/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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
sweep_idrequiredstring
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

sweepobject
Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or reverse_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. reverse_swept events occur when a transfer is reversed and Plaid undoes the credit or debit.
The total sum of the swept and reverse_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
idstring
Identifier of the sweep.
createdstring
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amountstring
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_codestring
The currency of the sweep, e.g. "USD".
request_idstring
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  },
8  "request_id": "saKrIBuEB9qJZno"
9}

/transfer/sweep/list

List sweeps

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

transfer/sweep/list

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_datestring
The start datetime of sweeps to return (RFC 3339 format).

Format: date-time
end_datestring
The end datetime of sweeps to return (RFC 3339 format).

Format: date-time
countinteger
The maximum number of sweeps to return.

Minimum: 1
Maximum: 25
Default: 25
offsetinteger
The number of sweeps to skip before returning results.

Default: 0
Minimum: 0 
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]
idstring
Identifier of the sweep.
createdstring
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amountstring
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_codestring
The currency of the sweep, e.g. "USD".
request_idstring
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    }
9  ],
10  "request_id": "saKrIBuEB9qJZno"
11}

/transfer/repayment/list

Lists historical repayments

The /transfer/repayment/list endpoint fetches repayments matching the given filters. Repayments are returned in reverse-chronological order (most recent first) starting at the given start_time.

transfer/repayment/list

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_datestring
The start datetime of repayments to return (RFC 3339 format).

Format: date-time
end_datestring
The end datetime of repayments to return (RFC 3339 format).

Format: date-time
countinteger
The maximum number of repayments to return.

Minimum: 1
Maximum: 25
Default: 25
offsetinteger
The number of repayments to skip before returning results.

Default: 0
Minimum: 0 
1const request: TransferRepaymentListRequest = {
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.transferRepaymentList(request);
9  const repayments = response.data.repayments;
10  for (const repayment of repayments) {
11    // iterate through repayments
12  }
13} catch (error) {
14  // handle error
15}
transfer/repayment/list

Response fields and example

repayments[object]
repayment_idstring
Identifier of the repayment.
createdstring
The datetime when the repayment occurred, in RFC 3339 format.

Format: date-time
amountstring
Decimal amount of the repayment as it appears on your account ledger.
iso_currency_codestring
The currency of the repayment, e.g. "USD".
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "repayments": [
3    {
4      "repayment_id": "d4bfce70-2470-4298-ae87-5e9b3e18bfaf",
5      "created": "2019-12-09T12:34:56Z",
6      "amount": "12.34",
7      "iso_currency_code": "USD"
8    }
9  ],
10  "request_id": "h0dvmW8g4r2Z0KX"
11}

/transfer/repayment/return/list

List the returns included in a repayment

The /transfer/repayment/return/list endpoint retrieves the set of returns that were batched together into the specified repayment. The sum of amounts of returns retrieved by this request equals the amount of the repayment.

transfer/repayment/return/list

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
repayment_idrequiredstring
Identifier of the repayment to query.
countinteger
The maximum number of repayments to return.

Minimum: 1
Maximum: 25
Default: 25
offsetinteger
The number of repayments to skip before returning results.

Default: 0
Minimum: 0 
1const request: TransferRepaymentReturnListRequest = {
2  repayment_id: '27ba0cc0-8d7c-4520-b162-1ff3c9cdf609',
3  count: 14,
4  offset: 2,
5};
6try {
7  const response = await plaidClient.transferRepaymentReturnList(request);
8  const repaymentReturns = response.data.repayment_returns;
9  for (const repaymentReturn of repaymentReturns) {
10    // iterate through repayment returns
11  }
12} catch (error) {
13  // handle error
14}
transfer/repayment/return/list

Response fields and example

repayment_returns[object]
transfer_idstring
The unique identifier of the guaranteed transfer that was returned.
event_idinteger
The unique identifier of the corresponding reversed transfer event.

Minimum: 0
amountstring
The value of the returned transfer.
iso_currency_codestring
The currency of the repayment, e.g. "USD".
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "repayment_returns": [
3    {
4      "transfer_id": "d4bfce70-2470-4298-ae87-5e9b3e18bfaf",
5      "event_id": 5,
6      "amount": "12.34",
7      "iso_currency_code": "USD"
8    }
9  ],
10  "request_id": "Ay70UHyBmbY0wUf"
11}

/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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
account_idstring
The Plaid account_id for the account that will be debited or credited.
moderequiredstring
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
amountrequiredstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
descriptionrequiredstring
A description for the underlying transfer. Maximum of 8 characters.

Min length: 1
Max length: 8
ach_classrequiredstring
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_idstring
Plaid’s unique identifier for the origination account for the intent. If not provided, the default account will be used.
userrequiredobject
The legal name and other information for the account holder.
legal_namerequiredstring
The user's legal name.
phone_numberstring
The user's phone number.
email_addressstring
The user's email address.
addressobject
The address associated with the account holder.
streetstring
The street number and name (i.e., "100 Market St.").
citystring
Ex. "San Francisco"
regionstring
The state or province (e.g., "CA").
postal_codestring
The postal code (e.g., "94103").
countrystring
A two-letter country code (e.g., "US").
metadataobject
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_codestring
The currency of the transfer amount, e.g. "USD"
require_guaranteeboolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guaranteed ACH 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_intentobject
Represents a transfer intent within Transfer UI.
idstring
Plaid's unique identifier for the transfer intent object.
createdstring
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
statusstring
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_idnullable 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_idstring
Plaid’s unique identifier for the origination account for the intent. If not provided, the default account will be used.
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
modestring
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_classstring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
descriptionstring
A description for the underlying transfer. Maximum of 8 characters.
metadatanullable 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_codestring
The currency of the transfer amount, e.g. "USD"
require_guaranteenullable boolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guaranteed ACH customers only).
request_idstring
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_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_intent_idrequiredstring
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_intentobject
Represents a transfer intent within Transfer UI.
idstring
Plaid's unique identifier for a transfer intent object.
createdstring
The datetime the transfer was created. This will be of the form 2006-01-02T15:04:05Z.

Format: date-time
statusstring
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_idnullable string
Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise.
failure_reasonnullable object
The reason for a failed transfer intent. Returned only if the transfer intent status is failed. Null otherwise.
error_typestring
A broad categorization of the error.
error_codestring
A code representing the reason for a failed transfer intent (i.e., an API error or the authorization being declined).
For a full listing of bank transfer errors, see Bank Transfers errors.
error_messagestring
A human-readable description of the code associated with a failed transfer intent.
authorization_decisionnullable 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 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_rationalenullable 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.
codestring
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.
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.
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.

Possible values: NSF, RISK, MANUALLY_VERIFIED_ITEM, LOGIN_REQUIRED, ERROR
descriptionstring
A human-readable description of the code associated with a transfer approval or transfer decline.
account_idnullable 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_idstring
Plaid’s unique identifier for the origination account used for the transfer.
amountstring
The amount of the transfer (decimal string with two digits of precision e.g. "10.00").
modestring
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_classstring
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
userobject
The legal name and other information for the account holder.
legal_namestring
The user's legal name.
phone_numbernullable string
The user's phone number.
email_addressnullable string
The user's email address.
addressnullable object
The address associated with the account holder.
streetnullable string
The street number and name (i.e., "100 Market St.").
citynullable string
Ex. "San Francisco"
regionnullable string
The state or province (e.g., "CA").
postal_codenullable string
The postal code (e.g., "94103").
countrynullable string
A two-letter country code (e.g., "US").
descriptionstring
A description for the underlying transfer. Maximum of 8 characters.
metadatanullable 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_codestring
The currency of the transfer amount, e.g. "USD"
require_guaranteenullable boolean
When true, the transfer requires a GUARANTEED decision by Plaid to proceed (Guaranteed ACH customers only).
guarantee_decisionnullable string
Indicates whether the transfer is guaranteed by Plaid (Guaranteed ACH 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_rationalenullable object
The rationale for Plaid's decision to not guarantee a transfer. Will be null unless guarantee_decision is NOT_GUARANTEED.
codestring
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 Guaranteed ACH 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.

Possible values: RETURN_BANK, RETURN_CUSTOMER, GUARANTEE_LIMIT_REACHED, RISK_ESTIMATE_UNAVAILABLE
descriptionstring
A human-readable description of why the transfer cannot be guaranteed.
request_idstring
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}

Webhooks

TRANSFER_EVENTS_UPDATE

Fired when new transfer events are available. Receiving this webhook indicates you should fetch the new events from /transfer/event/sync.

webhook_typestring
TRANSFER
webhook_codestring
TRANSFER_EVENTS_UPDATE
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "TRANSFER_EVENTS_UPDATE"
4}