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 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 InternetPossible values: ccd , ppd , tel , web | |||
user requiredobject The legal name and other information for the account holder.
| |||
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:
| |||
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. |
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 error20}
Response fields and example
bank_transfer object Represents a bank transfer within the Bank Transfers API.
| ||||||||||||||||||||||
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}
Was this helpful?
/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 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. |
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 error9}
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}
Was this helpful?
/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 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. |
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 error9}
Response fields and example
bank_transfer object Represents a bank transfer within the Bank Transfers API.
| ||||||||||||||||||||||
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}
Was this helpful?
/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 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 |
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 transfers14 }15} catch (error) {16 // handle error17}
Response fields and example
bank_transfers [object]
| ||||||||||||||||||||||
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}
Was this helpful?
/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.
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 |
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 events18 }19} catch (error) {20 // handle error21}
Response fields and example
bank_transfer_events [object]
| |||||||||||||
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}
Was this helpful?
/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.
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 |
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 events10 }11} catch (error) {12 // handle error13}
Response fields and example
bank_transfer_events [object]
| |||||||||||||
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}
Was this helpful?
/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 and example
client_id string Your Plaid API client_id . The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret string Your Plaid API secret . The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
account_number requiredstring The user's account number. |
routing_number requiredstring The user's routing number. |
wire_routing_number string The user's wire transfer routing number. This is the ABA number; for some institutions, this may differ from the ACH number used in routing_number . |
account_type requiredstring The type of the bank account ( checking or savings ). |
1const request: 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 error11}
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}
Was this helpful?
/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 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. |
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 error9}
Response fields and example
balance object Information about the balance of a bank transfer
| ||
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}
Was this helpful?
/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 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.
|
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 success9} catch (error) {10 // handle error11}
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}
Was this helpful?
/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 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. |
1const request: SandboxBankTransferFireWebhookRequest = {2 webhook: 'https://www.example.com',3};4try {5 const response = await plaidClient.sandboxBankTransferFireWebhook(request);6 // empty response upon success7} catch (error) {8 // handle error9}
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}
Was this helpful?
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}