Bank Transfer (beta) endpoints

API Reference guide for the Bank Transfer (beta) product

Endpoints
/bank_transfer/createInitiate a bank transfer
/bank_transfer/cancelCancel a bank transfer
/bank_transfer/getRetrieve data about a bank transfer
/bank_transfer/listFind bank transfers matching specified criteria
/bank_transfer/event/listRetrieve bank transfer events matching specified criteria
/bank_transfer/event/syncRetrieve bank transfer events after a given bank transfer event
/bank_transfer/migrate_accountCreate an Item to use with Bank Transfers from a known account number and routing number
/bank_transfer/balance/getRetrieve the balance on your Plaid bank transfer account
/sandbox/bank_transfer/simulateSimulate a bank transfer event
/sandbox/bank_transfer/fire_webhookSimulate a Bank Transfers webhook
Webhooks
BANK_TRANSFERS_EVENTS_UPDATENew bank transfer events available

Endpoints

/bank_transfer/create

Create a bank transfer

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

bank_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.
idempotency_key
requiredstring
A random key provided by the client, per unique bank 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 bank transfer fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single bank transfer is created.

Max length: 50
access_token
requiredstring
The Plaid access_token for the account that will be debited or credited.
account_id
requiredstring
The Plaid account_id for the account that will be debited or credited.
type
requiredstring
The type of bank 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. Valid options are ach, same-day-ach, or wire.

Possible values: ach, same-day-ach, wire
amount
requiredstring
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
requiredstring
The currency of the transfer amount – should be set to "USD".
description
requiredstring
The transfer description. Maximum of 10 characters.

Max length: 10
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 account holder’s full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
email_address
string
The account holder’s email.
routing_number
string
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
custom_tag
string
An arbitrary string provided by the client for storage with the bank transfer. May be up to 100 characters.

Max length: 100
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
origination_account_id
string
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.
Select group for content switcher
1const request: BankTransferCreateRequest = {
2  type: 'credit',
3  network: 'ach',
4  amount: '10.00',
5  iso_currency_code: 'USD',
6  description: 'payment',
7  ach_class: 'ppd',
8  user: {
9    legal_name: 'First Lastname',
10  },
11  access_token: accessToken,
12  idempotency_key: 'random string',
13  account_id: 'BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp',
14};
15try {
16  const response = await client.bankTransferCreate(request);
17  const bank_transfer = response.data.bank_transfer;
18} catch (error) {
19  // handle error
20}
bank_transfer/create

Response fields and example

bank_transfer
object
Represents a bank transfer within the Bank Transfers API.
id
string
Plaid’s unique identifier for a bank 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 bank transfer.
type
string
The type of bank 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 account holder’s full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
email_address
nullable string
The account holder’s email.
routing_number
string
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
amount
string
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the transfer.
created
string
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z

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

Possible values: pending, posted, cancelled, failed, reversed
network
string
The network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.

Possible values: ach, same-day-ach, wire
cancellable
boolean
When true, you can still cancel this bank transfer.
failure_reason
nullable object
The failure reason if the type of this transfer is "failed" or "reversed". 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 reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
custom_tag
nullable string
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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.
direction
nullable string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
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  "bank_transfer": {
3    "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "cancellable": true,
7    "created": "2020-08-06T17:27:15Z",
8    "custom_tag": "my tag",
9    "description": "Testing2",
10    "direction": "outbound",
11    "failure_reason": null,
12    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
13    "iso_currency_code": "USD",
14    "metadata": {
15      "key1": "value1",
16      "key2": "value2"
17    },
18    "network": "ach",
19    "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
20    "status": "pending",
21    "type": "credit",
22    "user": {
23      "email_address": "plaid@plaid.com",
24      "legal_name": "John Smith",
25      "routing_number": "111111111"
26    }
27  },
28  "request_id": "saKrIBuEB9qJZno"
29}

/bank_transfer/cancel

Cancel a bank transfer

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

bank_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.
bank_transfer_id
requiredstring
Plaid’s unique identifier for a bank transfer.
Select group for content switcher
1const request: BankTransferCancelRequest = {
2  bank_transfer_id,
3};
4try {
5  const response = await plaidClient.bankTransferCancel(request);
6  const request_id = response.data.request_id;
7} catch (error) {
8  // handle error
9}
bank_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}

/bank_transfer/get

Retrieve a bank transfer

The /bank_transfer/get fetches information about the bank transfer corresponding to the given bank_transfer_id.

bank_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.
bank_transfer_id
requiredstring
Plaid’s unique identifier for a bank transfer.
Select group for content switcher
1const request: BankTransferGetRequest = {
2  bank_transfer_id,
3};
4try {
5  const response = await plaidClient.bankTransferGet(request);
6  const bank_transfer = response.data.bank_transfer;
7} catch (error) {
8  // handle error
9}
bank_transfer/get

Response fields and example

bank_transfer
object
Represents a bank transfer within the Bank Transfers API.
id
string
Plaid’s unique identifier for a bank 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 bank transfer.
type
string
The type of bank 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 account holder’s full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
email_address
nullable string
The account holder’s email.
routing_number
string
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
amount
string
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the transfer.
created
string
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z

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

Possible values: pending, posted, cancelled, failed, reversed
network
string
The network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.

Possible values: ach, same-day-ach, wire
cancellable
boolean
When true, you can still cancel this bank transfer.
failure_reason
nullable object
The failure reason if the type of this transfer is "failed" or "reversed". 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 reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
custom_tag
nullable string
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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.
direction
nullable string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
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  "bank_transfer": {
3    "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
4    "ach_class": "ppd",
5    "amount": "12.34",
6    "cancellable": true,
7    "created": "2020-08-06T17:27:15Z",
8    "custom_tag": "my tag",
9    "description": "Testing2",
10    "direction": "outbound",
11    "failure_reason": {
12      "ach_return_code": "R13",
13      "description": "Invalid ACH routing number"
14    },
15    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
16    "iso_currency_code": "USD",
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    "user": {
26      "email_address": "plaid@plaid.com",
27      "legal_name": "John Smith",
28      "routing_number": "111111111"
29    }
30  },
31  "request_id": "saKrIBuEB9qJZno"
32}

/bank_transfer/list

List bank transfers

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

bank_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 bank 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 bank 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 bank transfers to return.

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

Default: 0
Minimum: 0
origination_account_id
string
Filter bank transfers to only those originated through the specified origination account.
direction
string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
Select group for content switcher
1const request: BankTransferListRequest = {
2  start_date: start_date,
3  end_date: end_date,
4  count: count,
5  offset: offset,
6  origination_account_id: origination_account_id,
7  direction: direction,
8};
9try {
10  const response = await plaidClient.bankTransferList(request);
11  const bank_transfers = response.data.bank_transfers;
12  for (const transfer of bank_transfers) {
13    // iterate through transfers
14  }
15} catch (error) {
16  // handle error
17}
bank_transfer/list

Response fields and example

bank_transfers
[object]
id
string
Plaid’s unique identifier for a bank 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 bank transfer.
type
string
The type of bank 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 account holder’s full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
email_address
nullable string
The account holder’s email.
routing_number
string
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
amount
string
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
description
string
The description of the transfer.
created
string
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z

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

Possible values: pending, posted, cancelled, failed, reversed
network
string
The network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.

Possible values: ach, same-day-ach, wire
cancellable
boolean
When true, you can still cancel this bank transfer.
failure_reason
nullable object
The failure reason if the type of this transfer is "failed" or "reversed". 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 reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
custom_tag
nullable string
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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.
direction
nullable string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
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  "bank_transfers": [
3    {
4      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
5      "ach_class": "ppd",
6      "amount": "12.34",
7      "cancellable": true,
8      "created": "2020-08-06T17:27:15Z",
9      "custom_tag": "my tag",
10      "description": "Testing2",
11      "direction": "outbound",
12      "failure_reason": {
13        "ach_return_code": "R13",
14        "description": "Invalid ACH routing number"
15      },
16      "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
17      "iso_currency_code": "USD",
18      "metadata": {
19        "key1": "value1",
20        "key2": "value2"
21      },
22      "network": "ach",
23      "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
24      "status": "pending",
25      "type": "credit",
26      "user": {
27        "email_address": "plaid@plaid.com",
28        "legal_name": "John Smith",
29        "routing_number": "111111111"
30      }
31    }
32  ],
33  "request_id": "saKrIBuEB9qJZno"
34}

/bank_transfer/event/list

List bank transfer events

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

bank_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 bank 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 bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
account_id
string
The account ID to get events for all transactions to/from an account.
bank_transfer_type
string
The type of bank 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
count
integer
The maximum number of bank 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 bank 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_id
string
The origination account ID to get events for transfers from a specific origination account.
direction
string
Indicates the direction of the transfer: outbound: for API-initiated transfers inbound: for payments received by the FBO account.

Possible values: inbound, outbound, null
Select group for content switcher
1const request: BankTransferEventListRequest = {
2  start_date: start_date,
3  end_date: end_date,
4  bank_transfer_id: bank_transfer_id,
5  account_id: account_id,
6  bank_transfer_type: bank_transfer_type,
7  event_types: event_types,
8  count: count,
9  offset: offset,
10  origination_account_id: origination_account_id,
11  direction: direction,
12};
13try {
14  const response = await plaidClient.bankTransferEventList(request);
15  const events = response.data.bank_transfer_events;
16  for (const event of events) {
17    // iterate through events
18  }
19} catch (error) {
20  // handle error
21}
bank_transfer/event/list

Response fields and example

bank_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 bank 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.

Possible values: pending, cancelled, failed, posted, reversed
account_id
string
The account ID associated with the bank transfer.
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
origination_account_id
nullable string
The ID of the origination account that this balance belongs to.
bank_transfer_type
string
The type of bank 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
bank_transfer_amount
string
The bank transfer amount.
bank_transfer_iso_currency_code
string
The currency of the bank transfer amount.
failure_reason
nullable object
The failure reason if the type of this transfer is "failed" or "reversed". 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 reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
direction
nullable string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
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  "bank_transfer_events": [
3    {
4      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
5      "bank_transfer_amount": "12.34",
6      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "bank_transfer_iso_currency_code": "USD",
8      "bank_transfer_type": "credit",
9      "direction": "outbound",
10      "event_id": 1,
11      "event_type": "pending",
12      "failure_reason": null,
13      "origination_account_id": null,
14      "timestamp": "2020-08-06T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}

/bank_transfer/event/sync

Sync bank transfer events

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

bank_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 bank transfer events to return.

Default: 25
Minimum: 1
Maximum: 25
Select group for content switcher
1const request: BankTransferEventListRequest = {
2  after_id: afterID,
3  count: 25,
4};
5try {
6  const response = await plaidClient.bankTransferEventSync(request);
7  const events = response.data.bank_transfer_events;
8  for (const event of events) {
9    // iterate through events
10  }
11} catch (error) {
12  // handle error
13}
bank_transfer/event/sync

Response fields and example

bank_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 bank 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.

Possible values: pending, cancelled, failed, posted, reversed
account_id
string
The account ID associated with the bank transfer.
bank_transfer_id
string
Plaid’s unique identifier for a bank transfer.
origination_account_id
nullable string
The ID of the origination account that this balance belongs to.
bank_transfer_type
string
The type of bank 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
bank_transfer_amount
string
The bank transfer amount.
bank_transfer_iso_currency_code
string
The currency of the bank transfer amount.
failure_reason
nullable object
The failure reason if the type of this transfer is "failed" or "reversed". 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 reversed. For a full listing of ACH return codes, see Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
direction
nullable string
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.

Possible values: outbound, inbound, null
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  "bank_transfer_events": [
3    {
4      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
5      "bank_transfer_amount": "12.34",
6      "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
7      "bank_transfer_iso_currency_code": "USD",
8      "bank_transfer_type": "credit",
9      "direction": "outbound",
10      "event_id": 1,
11      "event_type": "pending",
12      "failure_reason": null,
13      "origination_account_id": null,
14      "timestamp": "2020-08-06T17:27:15Z"
15    }
16  ],
17  "request_id": "mdqfuVxeoza6mhu"
18}

/bank_transfer/migrate_account

Migrate account into Bank Transfers

As an alternative to adding Items via Link, you can also use the /bank_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 Bank Transfer endpoints. If you require access to other endpoints, create the Item through Link instead. Access to /bank_transfer/migrate_account is not enabled by default; to obtain access, contact your Plaid Account Manager.

bank_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).
Select group for content switcher
1const request: BankTransferMigrateAccountRequest = {
2  account_number: '100000000',
3  routing_number: '121122676',
4  account_type: 'checking',
5};
6try {
7  const response = await plaidClient.bankTransferMigrateAccount(request);
8  const access_token = response.data.access_token;
9} catch (error) {
10  // handle error
11}
bank_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}

/bank_transfer/balance/get

Get balance of your Bank Transfer account

Use the /bank_transfer/balance/get endpoint to see the available balance in your bank transfer account. Debit transfers increase this balance once their status is posted. Credit transfers decrease this balance when they are created.
The transactable balance shows the amount in your account that you are able to use for transfers, and is essentially your available balance minus your minimum balance.
Note that this endpoint can only be used with FBO accounts, when using Bank Transfers in the Full Service configuration. It cannot be used on your own account when using Bank Transfers in the BTS Platform configuration.

bank_transfer/balance/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.
origination_account_id
string
If multiple origination accounts are available, origination_account_id must be used to specify the account for which balance will be returned.
Select group for content switcher
1const request: BankTransferBalanceGetRequest = {
2  origination_account_id,
3};
4try {
5  const response = await plaidClient.bankTransferBalanceGet(request);
6  const available_balance = response.data.balance.available;
7} catch (error) {
8  // handle error
9}
bank_transfer/balance/get

Response fields and example

balance
object
Information about the balance of a bank transfer
available
string
The total available balance - the sum of all successful debit transfer amounts minus all credit transfer amounts.
transactable
string
The transactable balance shows the amount in your account that you are able to use for transfers, and is essentially your available balance minus your minimum balance.
origination_account_id
nullable string
The ID of the origination account that this balance belongs to.
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  "balance": {
3    "available": "1721.70",
4    "transactable": "721.70"
5  },
6  "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
7  "request_id": "mdqfuVxeoza6mhu"
8}

/sandbox/bank_transfer/simulate

Simulate a bank transfer event in Sandbox

Use the /sandbox/bank_transfer/simulate endpoint to simulate a bank transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as /bank_transfer/event/sync or /bank_transfer/event/list, no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

sandbox/bank_transfer/simulate

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.
bank_transfer_id
requiredstring
Plaid’s unique identifier for a bank transfer.
event_type
requiredstring
The asynchronous event to be simulated. May be: posted, failed, or reversed.
An error will be returned if the event type is incompatible with the current transfer status. Compatible status --> event type transitions include:
pending --> failed
pending --> posted
posted --> reversed
failure_reason
object
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
ach_return_code
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 Bank Transfers errors.
description
string
A human-readable description of the reason for the failure or reversal.
Select group for content switcher
1const request: SandboxBankTransferSimulateRequest = {
2  bank_transfer_id,
3  event_type: 'posted',
4  failure_reason: failureReason,
5};
6try {
7  const response = await plaidClient.sandboxBankTransferSimulate(request);
8  // empty response upon success
9} catch (error) {
10  // handle error
11}
sandbox/bank_transfer/simulate

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": "LmHYMwBhZUvsM03"
3}

/sandbox/bank_transfer/fire_webhook

Manually fire a Bank Transfer webhook

Use the /sandbox/bank_transfer/fire_webhook endpoint to manually trigger a Bank Transfers webhook in the Sandbox environment.

sandbox/bank_transfer/fire_webhook

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.
webhook
requiredstring
The URL to which the webhook should be sent.
Select group for content switcher
1const request: SandboxBankTransferFireWebhookRequest = {
2  webhook: 'https://www.example.com',
3};
4try {
5  const response = await plaidClient.sandboxBankTransferFireWebhook(request);
6  // empty response upon success
7} catch (error) {
8  // handle error
9}
sandbox/bank_transfer/fire_webhook

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": "mdqfuVxeoza6mhu"
3}

Webhooks

BANK_TRANSFERS_EVENTS_UPDATE

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

webhook_type
string
BANK_TRANSFERS
webhook_code
string
BANK_TRANSFERS_EVENTS_UPDATE
1{
2  "webhook_type": "BANK_TRANSFERS",
3  "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE"
4}