Reading Transfers and Transfer events

API reference for Transfer read and Transfer event endpoints and webhooks

Reading Transfers
/transfer/getRetrieve information about a transfer
/transfer/listRetrieve a list of transfers and their statuses
/transfer/event/listRetrieve a list of transfer events
/transfer/event/syncSync transfer events
/transfer/sweep/getRetrieve information about a sweep
/transfer/sweep/listRetrieve a list of sweeps
Webhooks
TRANSFER_EVENTS_UPDATENew transfer events available

Endpoints

/transfer/get

Retrieve a transfer

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

transfer/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transfer_id
requiredstring
Plaid’s unique identifier for a transfer.
1const request: TransferGetRequest = {
2  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
3};
4try {
5  const response = await plaidClient.transferGet(request);
6  const transfer = response.data.transfer;
7} catch (error) {
8  // handle error
9}
transfer/get

Response fields and example

transfer
object
Represents a transfer within the Transfers API.
id
string
Plaid’s unique identifier for a transfer.
authorization_id
string
Plaid’s unique identifier for a transfer authorization.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
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, e.g. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization_id will be sent.
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
string
The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned
sweep_status
nullablestring
The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept
network
string
The network or rails used for the transfer.
For transfers submitted as ach, the next-day cutoff is 5:30 PM Eastern Time.
For transfers submitted as same-day-ach, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable.
For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp, wire
wire_details
nullableobject
Information specific to wire transfers.
message_to_beneficiary
nullablestring
Additional information from the wire originator to the beneficiary. Max 140 characters.
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullablestring
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date
unauthorized_return_window
nullablestring
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date
expected_settlement_date
nullablestring
The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.
refunds
[object]
A list of refunds associated with this transfer.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
recurring_transfer_id
nullablestring
The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule
[object]
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.
sweep_settlement_date
string
The settlement date of a sweep for this transfer.

Format: date
swept_settled_amount
string
The accumulated amount that has been swept by sweep_settlement_date.
credit_funds_source
deprecatednullablestring
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023.
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
facilitator_fee
string
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be less than or equal to the transfer.amount.
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer": {
3    "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
4    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
5    "ach_class": "ppd",
6    "amount": "12.34",
7    "cancellable": true,
8    "created": "2020-08-06T17:27:15Z",
9    "description": "Desc",
10    "guarantee_decision": null,
11    "guarantee_decision_rationale": null,
12    "failure_reason": {
13      "ach_return_code": "R13",
14      "description": "Invalid ACH routing number"
15    },
16    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
17    "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
18    "metadata": {
19      "key1": "value1",
20      "key2": "value2"
21    },
22    "network": "ach",
23    "origination_account_id": "",
24    "originator_client_id": null,
25    "refunds": [],
26    "status": "pending",
27    "type": "credit",
28    "iso_currency_code": "USD",
29    "standard_return_window": "2020-08-07",
30    "unauthorized_return_window": "2020-10-07",
31    "expected_settlement_date": "2020-08-04",
32    "user": {
33      "email_address": "acharleston@email.com",
34      "legal_name": "Anne Charleston",
35      "phone_number": "510-555-0128",
36      "address": {
37        "street": "123 Main St.",
38        "city": "San Francisco",
39        "region": "CA",
40        "postal_code": "94053",
41        "country": "US"
42      }
43    },
44    "recurring_transfer_id": null,
45    "credit_funds_source": "sweep",
46    "facilitator_fee": "1.23",
47    "network_trace_id": null
48  },
49  "request_id": "saKrIBuEB9qJZno"
50}

/transfer/list

List transfers

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

transfer/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_date
string
The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

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

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

Default: 0
Minimum: 0
originator_client_id
string
Filter transfers to only those with the specified originator client.
funding_account_id
string
Filter transfers to only those with the specified funding_account_id.
1const request: TransferListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
7};
8try {
9  const response = await plaidClient.transferList(request);
10  const transfers = response.data.transfers;
11  for (const transfer of transfers) {
12    // iterate through transfers
13  }
14} catch (error) {
15  // handle error
16}
transfer/list

Response fields and example

transfers
[object]
id
string
Plaid’s unique identifier for a transfer.
authorization_id
string
Plaid’s unique identifier for a transfer authorization.
ach_class
string
Specifies the use case of the transfer. Required for transfers on an ACH network.
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, e.g. bill payment
"tel" - Telephone-Initiated Entry
"web" - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet

Possible values: ccd, ppd, tel, web
account_id
string
The Plaid account_id corresponding to the end-user account that will be debited or credited.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into the origination account; a credit indicates a transfer of money out of the origination account.

Possible values: debit, credit
user
object
The legal name and other information for the account holder.
legal_name
string
The user's legal name.
phone_number
nullablestring
The user's phone number.
email_address
nullablestring
The user's email address.
address
nullableobject
The address associated with the account holder.
street
nullablestring
The street number and name (i.e., "100 Market St.").
city
nullablestring
Ex. "San Francisco"
region
nullablestring
The state or province (e.g., "CA").
postal_code
nullablestring
The postal code (e.g., "94103").
country
nullablestring
A two-letter country code (e.g., "US").
amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling /transfer/authorization/create, specify the maximum amount to authorize. When calling /transfer/create, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling /transfer/create, the maximum amount authorized in the authorization_id will be sent.
description
string
The description of the transfer.
created
string
The datetime when this transfer was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
status
string
The status of the transfer.
pending: A new transfer was created; it is in the pending state. posted: The transfer has been successfully submitted to the payment network. settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. cancelled: The transfer was cancelled by the client. failed: The transfer failed, no funds were moved. returned: A posted transfer was returned.

Possible values: pending, posted, settled, cancelled, failed, returned
sweep_status
nullablestring
The status of the sweep for the transfer.
unswept: The transfer hasn't been swept yet. swept: The transfer was swept to the sweep account. swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. return_swept: The transfer was returned, funds were pulled back or pushed back to the sweep account. null: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)

Possible values: null, unswept, swept, swept_settled, return_swept
network
string
The network or rails used for the transfer.
For transfers submitted as ach, the next-day cutoff is 5:30 PM Eastern Time.
For transfers submitted as same-day-ach, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable.
For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp, wire
wire_details
nullableobject
Information specific to wire transfers.
message_to_beneficiary
nullablestring
Additional information from the wire originator to the beneficiary. Max 140 characters.
cancellable
boolean
When true, you can still cancel this transfer.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
metadata
nullableobject
The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
iso_currency_code
string
The currency of the transfer amount, e.g. "USD"
standard_return_window
nullablestring
The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.

Format: date
unauthorized_return_window
nullablestring
The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.

Format: date
expected_settlement_date
nullablestring
The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.

Format: date
originator_client_id
nullablestring
The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a Platform customer.
refunds
[object]
A list of refunds associated with this transfer.
id
string
Plaid’s unique identifier for a refund.
transfer_id
string
The ID of the transfer to refund.
amount
string
The amount of the refund (decimal string with two digits of precision e.g. "10.00").
status
string
The status of the refund.
pending: A new refund was created; it is in the pending state. posted: The refund has been successfully submitted to the payment network. settled: Credits have been refunded to the Plaid linked account. cancelled: The refund was cancelled by the client. failed: The refund has failed. returned: The refund was returned.

Possible values: pending, posted, cancelled, failed, settled, returned
failure_reason
nullableobject
The failure reason if the event type for a refund is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the refund status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
created
string
The datetime when this refund was created. This will be of the form 2006-01-02T15:04:05Z

Format: date-time
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
recurring_transfer_id
nullablestring
The id of the recurring transfer if this transfer belongs to a recurring transfer.
expected_sweep_settlement_schedule
[object]
The expected sweep settlement schedule of this transfer, assuming this transfer is not returned. Only applies to ACH debit transfers.
sweep_settlement_date
string
The settlement date of a sweep for this transfer.

Format: date
swept_settled_amount
string
The accumulated amount that has been swept by sweep_settlement_date.
credit_funds_source
deprecatednullablestring
This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023.
Specifies the source of funds for the transfer. Only valid for credit transfers, and defaults to sweep if not specified. This field is not specified for debit transfers.
sweep - Sweep funds from your funding account prefunded_rtp_credits - Use your prefunded RTP credit balance with Plaid prefunded_ach_credits - Use your prefunded ACH credit balance with Plaid

Possible values: sweep, prefunded_rtp_credits, prefunded_ach_credits, null
facilitator_fee
string
The amount to deduct from transfer.amount and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be less than or equal to the transfer.amount.
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfers": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "ach_class": "ppd",
7      "amount": "12.34",
8      "cancellable": true,
9      "created": "2019-12-09T17:27:15Z",
10      "description": "Desc",
11      "guarantee_decision": null,
12      "guarantee_decision_rationale": null,
13      "failure_reason": {
14        "ach_return_code": "R13",
15        "description": "Invalid ACH routing number"
16      },
17      "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
18      "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",
19      "metadata": {
20        "key1": "value1",
21        "key2": "value2"
22      },
23      "network": "ach",
24      "origination_account_id": "",
25      "originator_client_id": null,
26      "refunds": [],
27      "status": "pending",
28      "type": "credit",
29      "iso_currency_code": "USD",
30      "standard_return_window": "2020-08-07",
31      "unauthorized_return_window": "2020-10-07",
32      "expected_settlement_date": "2020-08-04",
33      "user": {
34        "email_address": "acharleston@email.com",
35        "legal_name": "Anne Charleston",
36        "phone_number": "510-555-0128",
37        "address": {
38          "street": "123 Main St.",
39          "city": "San Francisco",
40          "region": "CA",
41          "postal_code": "94053",
42          "country": "US"
43        }
44      },
45      "recurring_transfer_id": null,
46      "credit_funds_source": "sweep",
47      "facilitator_fee": "1.23",
48      "network_trace_id": null
49    }
50  ],
51  "request_id": "saKrIBuEB9qJZno"
52}

/transfer/event/list

List transfer events

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

transfer/event/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
start_date
string
The start datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
end_date
string
The end datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z)

Format: date-time
transfer_id
string
Plaid’s unique identifier for a transfer.
account_id
string
The account ID to get events for all transactions to/from an account.
transfer_type
string
The type of transfer. This will be either debit or credit. A debit indicates a transfer of money into your origination account; a credit indicates a transfer of money out of your origination account.

Possible values: debit, credit, null
event_types
[string]
Filter events by event type.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed
sweep_id
string
Plaid’s unique identifier for a sweep.
count
integer
The maximum number of transfer events to return. If the number of events matching the above parameters is greater than count, the most recent events will be returned.

Default: 25
Maximum: 25
Minimum: 1
offset
integer
The offset into the list of transfer events. When count=25 and offset=0, the first 25 events will be returned. When count=25 and offset=25, the next 25 events will be returned.

Default: 0
Minimum: 0
originator_client_id
string
Filter transfer events to only those with the specified originator client.
funding_account_id
string
Filter transfer events to only those with the specified funding_account_id.
1const request: TransferEventListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',
5  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
6  transfer_type: 'credit',
7  event_types: ['pending', 'posted'],
8  count: 14,
9  offset: 2,
10  origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460',
11};
12try {
13  const response = await plaidClient.transferEventList(request);
14  const events = response.data.transfer_events;
15  for (const event of events) {
16    // iterate through events
17  }
18} catch (error) {
19  // handle error
20}
transfer/event/list

Response fields and example

transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

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

Format: date-time
event_type
string
The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.
sweep.pending: A new ledger sweep was created; it is in the pending state.
sweep.posted: The ledger sweep has been successfully submitted to the payment network.
sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun.
sweep.returned: A posted ledger sweep was returned.
sweep.failed: The ledger sweep failed, no funds were moved.
refund.pending: A new refund was created; it is in the pending state.
refund.cancelled: The refund was cancelled.
refund.failed: The refund failed, no funds were moved.
refund.posted: The refund has been successfully submitted to the payment network.
refund.settled: The refund transaction has settled in the Plaid linked account.
refund.returned: A posted refund was returned.
refund.swept: The refund was swept from the sweep account.
refund.return_swept: Due to the refund being returned, funds were pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed
account_id
string
The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
transfer_id
string
Plaid’s unique identifier for a transfer. This field is null for Plaid Ledger Sweep events.
transfer_type
string
The type of transfer. Valid values are 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. This field is omitted for Plaid Ledger Sweep events.

Possible values: debit, credit
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullablestring
Plaid’s unique identifier for a sweep.
sweep_amount
nullablestring
A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullablestring
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullablestring
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "transfer_amount": "12.34",
7      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
8      "transfer_type": "credit",
9      "event_id": 1,
10      "event_type": "posted",
11      "failure_reason": null,
12      "origination_account_id": "",
13      "originator_client_id": "569ed2f36b3a3a021713abc1",
14      "refund_id": null,
15      "sweep_amount": null,
16      "sweep_id": null,
17      "timestamp": "2019-12-09T17:27:15Z"
18    }
19  ],
20  "request_id": "mdqfuVxeoza6mhu"
21}

/transfer/event/sync

Sync transfer events

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

transfer/event/sync

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
after_id
requiredinteger
The latest (largest) event_id fetched via the sync endpoint, or 0 initially.

Minimum: 0
count
integer
The maximum number of transfer events to return.

Default: 25
Minimum: 1
Maximum: 25 
1const request: TransferEventListRequest = {
2  after_id: 4,
3  count: 22,
4};
5try {
6  const response = await plaidClient.transferEventSync(request);
7  const events = response.data.transfer_events;
8  for (const event of events) {
9    // iterate through events
10  }
11} catch (error) {
12  // handle error
13}
transfer/event/sync

Response fields and example

transfer_events
[object]
event_id
integer
Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers.

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

Format: date-time
event_type
string
The type of event that this transfer represents. Event types with prefix sweep represents events for Plaid Ledger sweeps.
pending: A new transfer was created; it is in the pending state.
cancelled: The transfer was cancelled by the client.
failed: The transfer failed, no funds were moved.
posted: The transfer has been successfully submitted to the payment network.
settled: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account.
returned: A posted transfer was returned.
swept: The transfer was swept to / from the sweep account.
swept_settled: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account.
return_swept: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account.
sweep.pending: A new ledger sweep was created; it is in the pending state.
sweep.posted: The ledger sweep has been successfully submitted to the payment network.
sweep.settled: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun.
sweep.returned: A posted ledger sweep was returned.
sweep.failed: The ledger sweep failed, no funds were moved.
refund.pending: A new refund was created; it is in the pending state.
refund.cancelled: The refund was cancelled.
refund.failed: The refund failed, no funds were moved.
refund.posted: The refund has been successfully submitted to the payment network.
refund.settled: The refund transaction has settled in the Plaid linked account.
refund.returned: A posted refund was returned.
refund.swept: The refund was swept from the sweep account.
refund.return_swept: Due to the refund being returned, funds were pushed back to the sweep account.

Possible values: pending, cancelled, failed, posted, settled, returned, swept, swept_settled, return_swept, sweep.pending, sweep.posted, sweep.settled, sweep.returned, sweep.failed
account_id
string
The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events.
funding_account_id
nullablestring
The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
transfer_id
string
Plaid’s unique identifier for a transfer. This field is null for Plaid Ledger Sweep events.
transfer_type
string
The type of transfer. Valid values are 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. This field is omitted for Plaid Ledger Sweep events.

Possible values: debit, credit
transfer_amount
string
The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events.
failure_reason
nullableobject
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
nullablestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
sweep_id
nullablestring
Plaid’s unique identifier for a sweep.
sweep_amount
nullablestring
A signed amount of how much was swept or return_swept for this transfer (decimal string with two digits of precision e.g. "-5.50").
refund_id
nullablestring
Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer.
originator_client_id
nullablestring
The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS).
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transfer_events": [
3    {
4      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "transfer_amount": "12.34",
7      "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
8      "transfer_type": "credit",
9      "event_id": 1,
10      "event_type": "pending",
11      "failure_reason": null,
12      "origination_account_id": "",
13      "originator_client_id": null,
14      "refund_id": null,
15      "sweep_amount": null,
16      "sweep_id": null,
17      "timestamp": "2019-12-09T17:27:15Z"
18    }
19  ],
20  "request_id": "mdqfuVxeoza6mhu"
21}

/transfer/sweep/get

Retrieve a sweep

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

transfer/sweep/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
sweep_id
requiredstring
Plaid's unique identifier for the sweep (UUID) or a shortened form consisting of the first 8 characters of the identifier (8-digit hexadecimal string).
1const request: TransferSweepGetRequest = {
2  sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee',
3};
4try {
5  const response = await plaidClient.transferSweepGet(request);
6  const sweep = response.data.sweep;
7} catch (error) {
8  // handle error
9}
transfer/sweep/get

Response fields and example

sweep
object
Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
id
string
Identifier of the sweep.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullablestring
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
status
nullablestring
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
trigger
nullablestring
The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate
description
string
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweep": {
3    "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
4    "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
5    "created": "2020-08-06T17:27:15Z",
6    "amount": "12.34",
7    "iso_currency_code": "USD",
8    "settled": "2020-08-07",
9    "status": "settled",
10    "network_trace_id": "123456789012345"
11  },
12  "request_id": "saKrIBuEB9qJZno"
13}

/transfer/sweep/list

List sweeps

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

transfer/sweep/list

Request fields and example

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

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

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

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

Default: 0
Minimum: 0
amount
string
Filter sweeps to only those with the specified amount.
status
string
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
originator_client_id
string
Filter sweeps to only those with the specified originator client.
funding_account_id
string
Filter sweeps to only those with the specified funding_account_id.
transfer_id
string
Filter sweeps to only those with the included transfer_id.
trigger
string
The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate
1const request: TransferSweepListRequest = {
2  start_date: '2019-12-06T22:35:49Z',
3  end_date: '2019-12-12T22:35:49Z',
4  count: 14,
5  offset: 2,
6};
7try {
8  const response = await plaidClient.transferSweepList(request);
9  const sweeps = response.data.sweeps;
10  for (const sweep of sweeps) {
11    // iterate through sweeps
12  }
13} catch (error) {
14  // handle error
15}
transfer/sweep/list

Response fields and example

sweeps
[object]
id
string
Identifier of the sweep.
funding_account_id
string
The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
settled
nullablestring
The date when the sweep settled, in the YYYY-MM-DD format.

Format: date
status
nullablestring
The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null
trigger
nullablestring
The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate
description
string
The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.
network_trace_id
nullablestring
The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "sweeps": [
3    {
4      "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
5      "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
6      "created": "2019-12-09T17:27:15Z",
7      "amount": "-12.34",
8      "iso_currency_code": "USD",
9      "settled": "2019-12-10",
10      "status": "settled",
11      "originator_client_id": null
12    }
13  ],
14  "request_id": "saKrIBuEB9qJZno"
15}

Webhooks

TRANSFER_EVENTS_UPDATE

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

webhook_type
string
TRANSFER
webhook_code
string
TRANSFER_EVENTS_UPDATE
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "TRANSFER",
3  "webhook_code": "TRANSFER_EVENTS_UPDATE",
4  "environment": "production"
5}