Bank Transfer (beta) endpoints
API Reference guide for the Bank Transfer (beta) product
| Endpoints | |
|---|---|
/bank_transfer/create | Initiate a bank transfer |
/bank_transfer/cancel | Cancel a bank transfer |
/bank_transfer/get | Retrieve data about a bank transfer |
/bank_transfer/list | Find bank transfers matching specified criteria |
/bank_transfer/event/list | Retrieve bank transfer events matching specified criteria |
/bank_transfer/event/sync | Retrieve bank transfer events after a given bank transfer event |
/bank_transfer/migrate_account | Create an Item to use with Bank Transfers from a known account number and routing number |
/bank_transfer/balance/get | Retrieve the balance on your Plaid bank transfer account |
/sandbox/bank_transfer/simulate | Simulate a bank transfer event |
/sandbox/bank_transfer/fire_webhook | Simulate a Bank Transfers webhook |
| Webhooks | |
|---|---|
BANK_TRANSFERS_EVENTS_UPDATE | New bank transfer events available |
Endpoints
/bank_transfer/create
Create a bank transfer
Use the /bank_transfer/create endpoint to initiate a new bank transfer.
Request fields
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.
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.
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.
50 The Plaid access_token for the account that will be debited or credited.
The Plaid account_id for the account that will be debited or credited.
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.
debit, creditThe network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.
ach, same-day-ach, wireThe amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
The currency of the transfer amount - should be set to "USD".
The transfer description. Maximum of 10 characters.
10 Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes.
Codes supported for credits: ccd, ppd
Codes supported for debits: ccd, tel, web
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits.
"web" - Internet-Initiated Entry. The transfer debits a consumer's bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.
"tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call.
ccd, ppd, tel, webThe legal name and other information for the account holder.
The account holder's full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
The account holder's email.
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
An arbitrary string provided by the client for storage with the bank transfer. May be up to 100 characters.
100 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
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.
const request: BankTransferCreateRequest = {
type: 'credit',
network: 'ach',
amount: '10.00',
iso_currency_code: 'USD',
description: 'payment',
ach_class: 'ppd',
user: {
legal_name: 'First Lastname',
},
access_token: accessToken,
idempotency_key: 'random string',
account_id: 'BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp',
};
try {
const response = await client.bankTransferCreate(request);
const bank_transfer = response.data.bank_transfer;
} catch (error) {
// handle error
}
Response fields
Represents a bank transfer within the Bank Transfers API.
Plaid's unique identifier for a bank transfer.
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes.
Codes supported for credits: ccd, ppd
Codes supported for debits: ccd, tel, web
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits.
"web" - Internet-Initiated Entry. The transfer debits a consumer's bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.
"tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call.
ccd, ppd, tel, webThe account ID that should be credited/debited for this bank transfer.
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.
debit, creditThe legal name and other information for the account holder.
The account holder's full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
The account holder's email.
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
The currency of the transfer amount, e.g. "USD"
The description of the transfer.
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z
date-time The status of the transfer.
pending, posted, cancelled, failed, reversedThe network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.
ach, same-day-ach, wireWhen true, you can still cancel this bank transfer.
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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
Plaid's unique identifier for the origination account that was used for this transfer.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"bank_transfer": {
"account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
"ach_class": "ppd",
"amount": "12.34",
"cancellable": true,
"created": "2020-08-06T17:27:15Z",
"custom_tag": "my tag",
"description": "Testing2",
"direction": "outbound",
"failure_reason": null,
"id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
"iso_currency_code": "USD",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"network": "ach",
"origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
"status": "pending",
"type": "credit",
"user": {
"email_address": "plaid@plaid.com",
"legal_name": "John Smith",
"routing_number": "111111111"
}
},
"request_id": "saKrIBuEB9qJZno"
}/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.
Request fields
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.
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.
Plaid's unique identifier for a bank transfer.
const request: BankTransferCancelRequest = {
bank_transfer_id,
};
try {
const response = await plaidClient.bankTransferCancel(request);
const request_id = response.data.request_id;
} catch (error) {
// handle error
}
Response fields
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"request_id": "saKrIBuEB9qJZno"
}/bank_transfer/get
Retrieve a bank transfer
The /bank_transfer/get fetches information about the bank transfer corresponding to the given bank_transfer_id.
Request fields
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.
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.
Plaid's unique identifier for a bank transfer.
const request: BankTransferGetRequest = {
bank_transfer_id,
};
try {
const response = await plaidClient.bankTransferGet(request);
const bank_transfer = response.data.bank_transfer;
} catch (error) {
// handle error
}
Response fields
Represents a bank transfer within the Bank Transfers API.
Plaid's unique identifier for a bank transfer.
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes.
Codes supported for credits: ccd, ppd
Codes supported for debits: ccd, tel, web
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits.
"web" - Internet-Initiated Entry. The transfer debits a consumer's bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.
"tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call.
ccd, ppd, tel, webThe account ID that should be credited/debited for this bank transfer.
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.
debit, creditThe legal name and other information for the account holder.
The account holder's full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
The account holder's email.
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
The currency of the transfer amount, e.g. "USD"
The description of the transfer.
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z
date-time The status of the transfer.
pending, posted, cancelled, failed, reversedThe network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.
ach, same-day-ach, wireWhen true, you can still cancel this bank transfer.
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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
Plaid's unique identifier for the origination account that was used for this transfer.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"bank_transfer": {
"account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
"ach_class": "ppd",
"amount": "12.34",
"cancellable": true,
"created": "2020-08-06T17:27:15Z",
"custom_tag": "my tag",
"description": "Testing2",
"direction": "outbound",
"failure_reason": {
"ach_return_code": "R13",
"description": "Invalid ACH routing number"
},
"id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
"iso_currency_code": "USD",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"network": "ach",
"origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
"status": "pending",
"type": "credit",
"user": {
"email_address": "plaid@plaid.com",
"legal_name": "John Smith",
"routing_number": "111111111"
}
},
"request_id": "saKrIBuEB9qJZno"
}/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.
Request fields
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.
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.
The start datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)
date-time The end datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)
date-time The maximum number of bank transfers to return.
1 25 25 The number of bank transfers to skip before returning results.
0 0 Filter bank transfers to only those originated through the specified origination account.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullconst request: BankTransferListRequest = {
start_date: start_date,
end_date: end_date,
count: count,
offset: offset,
origination_account_id: origination_account_id,
direction: direction,
};
try {
const response = await plaidClient.bankTransferList(request);
const bank_transfers = response.data.bank_transfers;
for (const transfer of bank_transfers) {
// iterate through transfers
}
} catch (error) {
// handle error
}
Response fields
Plaid's unique identifier for a bank transfer.
Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see ACH SEC codes.
Codes supported for credits: ccd, ppd
Codes supported for debits: ccd, tel, web
"ccd" - Corporate Credit or Debit - fund transfer between two corporate bank accounts
"ppd" - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits.
"web" - Internet-Initiated Entry. The transfer debits a consumer's bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.
"tel" - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call.
ccd, ppd, tel, webThe account ID that should be credited/debited for this bank transfer.
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.
debit, creditThe legal name and other information for the account holder.
The account holder's full legal name. If the transfer ach_class is ccd, this should be the business name of the account holder.
The account holder's email.
The account holder's routing number. This field is only used in response data. Do not provide this field when making requests.
The amount of the bank transfer (decimal string with two digits of precision e.g. "10.00").
The currency of the transfer amount, e.g. "USD"
The description of the transfer.
The datetime when this bank transfer was created. This will be of the form 2006-01-02T15:04:05Z
date-time The status of the transfer.
pending, posted, cancelled, failed, reversedThe network or rails used for the transfer. Valid options are ach, same-day-ach, or wire.
ach, same-day-ach, wireWhen true, you can still cancel this bank transfer.
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
A string containing the custom tag provided by the client in the create request. Will be null if not provided.
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
Plaid's unique identifier for the origination account that was used for this transfer.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"bank_transfers": [
{
"account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
"ach_class": "ppd",
"amount": "12.34",
"cancellable": true,
"created": "2020-08-06T17:27:15Z",
"custom_tag": "my tag",
"description": "Testing2",
"direction": "outbound",
"failure_reason": {
"ach_return_code": "R13",
"description": "Invalid ACH routing number"
},
"id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
"iso_currency_code": "USD",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"network": "ach",
"origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
"originator_client_id": "569ed2f36b3a3a021713abc1",
"status": "pending",
"type": "credit",
"user": {
"email_address": "plaid@plaid.com",
"legal_name": "John Smith",
"routing_number": "111111111"
}
}
],
"request_id": "saKrIBuEB9qJZno"
}/bank_transfer/event/list
List bank transfer events
Use the /bank_transfer/event/list endpoint to get a list of Plaid-initiated ACH or bank transfer events based on specified filter criteria. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see micro-deposit events.
Request fields
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.
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.
The start datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)
date-time The end datetime of bank transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)
date-time Plaid's unique identifier for a bank transfer.
The account ID to get events for all transactions to/from an account.
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.
debit, credit, nullFilter events by event type.
pending, cancelled, failed, posted, reversedThe 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.
25 25 1 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.
0 0 The origination account ID to get events for transfers from a specific origination account.
Indicates the direction of the transfer: outbound: for API-initiated transfers
inbound: for payments received by the FBO account.
inbound, outbound, nullconst request: BankTransferEventListRequest = {
start_date: start_date,
end_date: end_date,
bank_transfer_id: bank_transfer_id,
account_id: account_id,
bank_transfer_type: bank_transfer_type,
event_types: event_types,
count: count,
offset: offset,
origination_account_id: origination_account_id,
direction: direction,
};
try {
const response = await plaidClient.bankTransferEventList(request);
const events = response.data.bank_transfer_events;
for (const event of events) {
// iterate through events
}
} catch (error) {
// handle error
}
Response fields
Plaid's unique identifier for this event. IDs are sequential unsigned 64-bit integers.
0 The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.
date-time 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.
pending, cancelled, failed, posted, reversedThe account ID associated with the bank transfer.
Plaid's unique identifier for a bank transfer.
The ID of the origination account that this balance belongs to.
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.
debit, creditThe bank transfer amount.
The currency of the bank transfer amount.
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"bank_transfer_events": [
{
"account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
"bank_transfer_amount": "12.34",
"bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
"bank_transfer_iso_currency_code": "USD",
"bank_transfer_type": "credit",
"direction": "outbound",
"event_id": 1,
"event_type": "pending",
"failure_reason": null,
"origination_account_id": "",
"timestamp": "2020-08-06T17:27:15Z"
}
],
"request_id": "mdqfuVxeoza6mhu"
}/bank_transfer/event/sync
Sync bank transfer events
/bank_transfer/event/sync allows you to request up to the next 25 Plaid-initiated bank transfer events that happened after a specific event_id. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see micro-deposit events.
Request fields
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.
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.
The latest (largest) event_id fetched via the sync endpoint, or 0 initially.
0 The maximum number of bank transfer events to return.
25 1 25 const request: BankTransferEventListRequest = {
after_id: afterID,
count: 25,
};
try {
const response = await plaidClient.bankTransferEventSync(request);
const events = response.data.bank_transfer_events;
for (const event of events) {
// iterate through events
}
} catch (error) {
// handle error
}
Response fields
Plaid's unique identifier for this event. IDs are sequential unsigned 64-bit integers.
0 The datetime when this event occurred. This will be of the form 2006-01-02T15:04:05Z.
date-time 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.
pending, cancelled, failed, posted, reversedThe account ID associated with the bank transfer.
Plaid's unique identifier for a bank transfer.
The ID of the origination account that this balance belongs to.
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.
debit, creditThe bank transfer amount.
The currency of the bank transfer amount.
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
Indicates the direction of the transfer: outbound for API-initiated transfers, or inbound for payments received by the FBO account.
outbound, inbound, nullA unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"bank_transfer_events": [
{
"account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
"bank_transfer_amount": "12.34",
"bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
"bank_transfer_iso_currency_code": "USD",
"bank_transfer_type": "credit",
"direction": "outbound",
"event_id": 1,
"event_type": "pending",
"failure_reason": null,
"origination_account_id": "",
"timestamp": "2020-08-06T17:27:15Z"
}
],
"request_id": "mdqfuVxeoza6mhu"
}/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.
Request fields
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.
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.
The user's account number.
The user's routing number.
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.
The type of the bank account (checking or savings).
const request: BankTransferMigrateAccountRequest = {
account_number: '100000000',
routing_number: '121122676',
account_type: 'checking',
};
try {
const response = await plaidClient.bankTransferMigrateAccount(request);
const access_token = response.data.access_token;
} catch (error) {
// handle error
}
Response fields
The Plaid access_token for the newly created Item.
The Plaid account_id for the newly created Item.
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0",
"account_id": "zvyDgbeeDluZ43AJP6m5fAxDlgoZXDuoy5gjN",
"request_id": "mdqfuVxeoza6mhu"
}/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.
Request fields
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.
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.
If multiple origination accounts are available, origination_account_id must be used to specify the account for which balance will be returned.
const request: BankTransferBalanceGetRequest = {
origination_account_id,
};
try {
const response = await plaidClient.bankTransferBalanceGet(request);
const available_balance = response.data.balance.available;
} catch (error) {
// handle error
}
Response fields
Information about the balance of a bank transfer
The total available balance - the sum of all successful debit transfer amounts minus all credit transfer amounts.
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.
The ID of the origination account that this balance belongs to.
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"balance": {
"available": "1721.70",
"transactable": "721.70"
},
"origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
"request_id": "mdqfuVxeoza6mhu"
}/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.
Request fields
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.
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.
Plaid's unique identifier for a bank transfer.
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
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
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.
A human-readable description of the reason for the failure or reversal.
const request: SandboxBankTransferSimulateRequest = {
bank_transfer_id,
event_type: 'posted',
failure_reason: failureReason,
};
try {
const response = await plaidClient.sandboxBankTransferSimulate(request);
// empty response upon success
} catch (error) {
// handle error
}
Response fields
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"request_id": "LmHYMwBhZUvsM03"
}/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.
Request fields
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.
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.
The URL to which the webhook should be sent.
url const request: SandboxBankTransferFireWebhookRequest = {
webhook: 'https://www.example.com',
};
try {
const response = await plaidClient.sandboxBankTransferFireWebhook(request);
// empty response upon success
} catch (error) {
// handle error
}
Response fields
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
"request_id": "mdqfuVxeoza6mhu"
}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.
Properties
BANK_TRANSFERS
BANK_TRANSFERS_EVENTS_UPDATE
The Plaid environment the webhook was sent from
sandbox, production{
"webhook_type": "BANK_TRANSFERS",
"webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE",
"environment": "production"
}