Transfer
API reference for Transfer endpoints and webhooks
Intelligently process transfers between accounts in the US.
Transfer endpoints are only supported in Plaid's Sandbox and Production environments.
Initiating Transfers | |
---|---|
/transfer/authorization/create | Create a transfer authorization |
/transfer/create | Create a transfer |
/transfer/cancel | Cancel a transfer |
Reading Transfers | |
---|---|
/transfer/get | Retrieve information about a transfer |
/transfer/list | Retrieve a list of transfers and their statuses |
/transfer/event/list | Retrieve a list of transfer events |
/transfer/event/sync | Sync transfer events |
/transfer/sweep/get | Retrieve information about a sweep |
/transfer/sweep/list | Retrieve a list of sweeps |
Account Linking | |
---|---|
/transfer/capabilities/get | Determine RTP eligibility for a Plaid Item |
/transfer/intent/create | Create a transfer intent and invoke Transfer UI (Transfer UI only) |
/transfer/intent/get | Retrieve information about a transfer intent (Transfer UI only) |
/transfer/migrate_account | Create an Item to use with Transfer from known account and routing numbers |
Recurring Transfers | |
---|---|
/transfer/recurring/create | Create a recurring transfer |
/transfer/recurring/cancel | Cancel a recurring transfer |
/transfer/recurring/get | Retrieve information about a recurring transfer |
/transfer/recurring/list | Retrieve a list of recurring transfers |
Refunds | |
---|---|
/transfer/refund/create | Create a refund for a transfer |
/transfer/refund/cancel | Cancel a refund |
/transfer/refund/get | Retrieve information about a refund |
Platform Payments | |
---|---|
/transfer/originator/create | Create a new originator |
/transfer/originator/get | Get the status of an originator's onboarding |
/transfer/originator/list | Get the status of all originators' onboarding |
/transfer/originator/funding_account/update | Update the default funding account of an originator |
/transfer/questionnaire/create | Generate a Plaid-hosted onboarding UI URL |
/transfer/diligence/submit | Submit transfer diligence on behalf of the originator |
/transfer/diligence/document/upload | Upload transfer diligence document on behalf of the originator |
Plaid Ledger | |
---|---|
/transfer/ledger/deposit | Deposit funds into a ledger balance held with Plaid |
/transfer/ledger/get | Retrieve information about the ledger balance held with Plaid |
/transfer/ledger/withdraw | Withdraw funds from a ledger balance held with Plaid |
Program Metrics | |
---|---|
/transfer/metrics/get | Get transfer product usage metrics |
/transfer/configuration/get | Get transfer product configuration |
Balances | |
---|---|
/transfer/balance/get | Retrieve information about a balance held with Plaid |
Sandbox | |
---|---|
/sandbox/transfer/simulate | Simulate a transfer event (Sandbox only) |
/sandbox/transfer/sweep/simulate | Simulate creating a sweep (Sandbox only) |
/sandbox/transfer/fire_webhook | Simulate a transfer webhook (Sandbox only) |
/sandbox/transfer/ledger/deposit/simulate | Simulate a deposit sweep event (Sandbox only) |
/sandbox/transfer/ledger/simulate_available | Simulate converting pending balance into available balance (Sandbox only) |
/sandbox/transfer/ledger/withdraw/simulate | Simulate a withdraw sweep event (Sandbox only) |
/sandbox/transfer/test_clock/create | Create a test clock (Sandbox only) |
/sandbox/transfer/test_clock/advance | Advance a test clock (Sandbox only) |
/sandbox/transfer/test_clock/get | Retrieve information about a test clock (Sandbox only) |
/sandbox/transfer/test_clock/list | Retrieve a list of test clocks (Sandbox only) |
Webhooks | |
---|---|
TRANSFER_EVENTS_UPDATE | New transfer events available |
RECURRING_CANCELLED | A recurring transfer has been cancelled by Plaid |
RECURRING_NEW_TRANSFER | A new transfer of a recurring transfer has been originated |
RECURRING_TRANSFER_SKIPPED | An instance of a scheduled recurring transfer could not be created |
Endpoints
/transfer/authorization/create
Create a transfer authorization
Use the /transfer/authorization/create
endpoint to authorize a transfer. This endpoint must be called prior to calling /transfer/create
.
There are three possible outcomes to calling this endpoint: If the authorization.decision
in the response is declined
, the proposed transfer has failed the risk check and you cannot proceed with the transfer. If the authorization.decision
is approved
, and the authorization.rationale_code
is null
, the transfer has passed the risk check and you can proceed to call /transfer/create
. If the authorization.decision
is approved
and the authorization.rationale_code
is non-null
, the risk check could not be run: you may proceed with the transfer, but should perform your own risk evaluation. For more details, see the response schema.
In Plaid's Sandbox environment the decisions will be returned as follows:
- To approve a transfer with null
rationale code, make an authorization request with an amount
less than the available balance in the account.
- To approve a transfer with the rationale code MANUALLY_VERIFIED_ITEM
, create an Item in Link through the Same Day Micro-deposits flow.
- To approve a transfer with the rationale code ITEM_LOGIN_REQUIRED
, reset the login for an Item.
- To decline a transfer with the rationale code NSF
, the available balance on the account must be less than the authorization amount
. See Create Sandbox test data for details on how to customize data in Sandbox.
- To decline a transfer with the rationale code RISK
, the available balance on the account must be exactly $0. See Create Sandbox test data for details on how to customize data in Sandbox.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
access_token
for the account that will be debited or credited.account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
funding_account_id
s in the Accounts page of your Plaid Dashboard, under the "Account ID" column.type
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
, credit
network
For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get
before calling /transfer/authorization/create
.ach
, same-day-ach
, rtp
amount
ach_class
"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 Internetccd
, ppd
, tel
, web
user
user.legal_name
field is required. Other fields are not currently used and are present to support planned future functionality.legal_name
phone_number
email_address
address
street
city
region
postal_code
country
device
ip_address
user_agent
iso_currency_code
idempotency_key
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created.
This idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges.
50
user_present
true
; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false
. This field is not currently used and is present to support planned future functionality.originator_client_id
credit_funds_source
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 Plaidsweep
, prefunded_rtp_credits
, prefunded_ach_credits
, null
test_clock_id
sandbox
environment. If provided, the authorization
is created at the virtual_time
on the provided test clock.1const request: TransferAuthorizationCreateRequest = {2 access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',3 account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',4 type: 'credit',5 network: 'ach',6 amount: '12.34',7 ach_class: 'ppd',8 user: {9 legal_name: 'Anne Charleston',10 },11};1213try {14 const response = await client.transferAuthorizationCreate(request);15 const authorizationId = response.data.authorization.id;16} catch (error) {17 // handle error18}
Response fields and example
authorization
id
created
2006-01-02T15:04:05Z
.date-time
decision
approved
– The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale
field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code
is ITEM_LOGIN_REQUIRED
). Refer to the code
field in the decision_rationale
object for details.declined
– Plaid reviewed the proposed transfer and declined processing. Refer to the code
field in the decision_rationale
object for details.approved
, declined
decision_rationale
declined
decisions, and may or may not be null for approved
decisions.code
If the
rationale_code
is null
, the transfer passed the authorization check. Any non-
null
value for an approved
transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved
transfer are:MANUALLY_VERIFIED_ITEM
– Item created via same-day micro deposits, limited information available. ITEM_LOGIN_REQUIRED
– Unable to collect the account information due to Item staleness. Can be resolved by using Link in update mode. MIGRATED_ACCOUNT_ITEM
- Item created via /transfer/account_migration
endpoint, limited information available.ERROR
– Unable to collect the account information due to an unspecified error.The following codes indicate that the authorization decision was
declined
:NSF
– Transaction likely to result in a return due to insufficient funds. RISK
- Transaction is high-risk. TRANSFER_LIMIT_REACHED
- One or several transfer limits are reached, e.g. monthly transfer limit.NSF
, RISK
, TRANSFER_LIMIT_REACHED
, MANUALLY_VERIFIED_ITEM
, ITEM_LOGIN_REQUIRED
, PAYMENT_PROFILE_LOGIN_REQUIRED
, ERROR
, MIGRATED_ACCOUNT_ITEM
, null
description
payment_risk
bank_initiated_return _score
The score evaluates the transaction return risk because an account is overdrawn or because an ineligible account is used and covers return codes: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.
1
99
customer_initiated _return_score
The score evaluates the transaction return risk of an unauthorized debit and covers return codes: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.
1
99
risk_level
HIGH_RISK
, MEDIUM_HIGH_RISK
, MEDIUM_RISK
, MEDIUM_LOW_RISK
, LOW_RISK
warnings
warning_type
warning_code
ITEM_LOGIN_REQUIRED
warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.warning_message
proposed_transfer
ach_class
"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 Internetccd
, ppd
, tel
, web
account_id
account_id
for the account that will be debited or credited.funding_account_id
type
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
, credit
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
amount
network
iso_currency_code
originator_client_id
credit_funds_source
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 Plaidsweep
, prefunded_rtp_credits
, prefunded_ach_credits
, null
request_id
1{2 "authorization": {3 "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",4 "created": "2020-08-06T17:27:15Z",5 "decision": "approved",6 "decision_rationale": null,7 "guarantee_decision": null,8 "guarantee_decision_rationale": null,9 "payment_risk": null,10 "proposed_transfer": {11 "ach_class": "ppd",12 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",13 "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",14 "type": "credit",15 "user": {16 "legal_name": "Anne Charleston",17 "phone_number": "510-555-0128",18 "email_address": "acharleston@email.com",19 "address": {20 "street": "123 Main St.",21 "city": "San Francisco",22 "region": "CA",23 "postal_code": "94053",24 "country": "US"25 }26 },27 "amount": "12.34",28 "network": "ach",29 "iso_currency_code": "USD",30 "origination_account_id": "",31 "originator_client_id": null,32 "credit_funds_source": "sweep"33 }34 },35 "request_id": "saKrIBuEB9qJZno"36}
Was this helpful?
/transfer/balance/get
Retrieve a balance held with Plaid
Use the /transfer/balance/get
endpoint to view a balance held with Plaid.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.type
prefunded_rtp_credits
- Your prefunded RTP credit balance with Plaid
prefunded_ach_credits
- Your prefunded ACH credit balance with Plaidprefunded_rtp_credits
, prefunded_ach_credits
1const request: TransferBalanceGetRequest = {2 type: 'prefunded_rtp_credits',3};45try {6 const response = await client.transferBalanceGet(request);7 const available_balance = response.data.balance.available;8} catch (error) {9 // handle error10}
Response fields and example
balance
available
current
type
prefunded_rtp_credits
- Your prefunded RTP credit balance with Plaid
prefunded_ach_credits
- Your prefunded ACH credit balance with Plaidprefunded_rtp_credits
, prefunded_ach_credits
request_id
1{2 "balance": {3 "available": "1721.70",4 "type": "prefunded_rtp_credits"5 },6 "request_id": "saKrIBuEB9qJZno"7}
Was this helpful?
/transfer/capabilities/get
Get RTP eligibility information of a transfer
Use the /transfer/capabilities/get
endpoint to determine the RTP eligibility information of a transfer.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
access_token
for the account that will be debited or credited.account_id
account_id
corresponding to the end-user account that will be debited or credited.1const request: TransferCapabilitiesGetRequest = {2 access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',3 account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',4};56try {7 const response = await client.transferAuthorizationCreate(request);8 const authorizationId = response.data.authorization.id;9} catch (error) {10 // handle error11}
Response fields and example
institution_supported _networks
request_id
1{2 "institution_supported_networks": {3 "rtp": {4 "credit": true5 }6 },7 "request_id": "saKrIBuEB9qJZno"8}
Was this helpful?
/transfer/configuration/get
Get transfer product configuration
Use the /transfer/configuration/get
endpoint to view your transfer product configurations.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.originator_client_id
client_id
is a third-party sender (TPS).1const request: TransferConfigurationGetRequest = {2 originator_client_id: '61b8f48ded273e001aa8db6d',3};45try {6 const response = await client.transferConfigurationGet(request);7} catch (error) {8 // handle error9}
Response fields and example
request_id
max_single_transfer _amount
max_single_transfer _credit_amount
max_single_transfer _debit_amount
max_daily_credit _amount
max_daily_debit_amount
max_monthly_amount
max_monthly_credit _amount
max_monthly_debit _amount
iso_currency_code
1{2 "max_single_transfer_amount": "1000.00",3 "max_single_transfer_credit_amount": "1000.00",4 "max_single_transfer_debit_amount": "1000.00",5 "max_daily_credit_amount": "50000.00",6 "max_daily_debit_amount": "50000.00",7 "max_monthly_amount": "500000.00",8 "max_monthly_credit_amount": "500000.00",9 "max_monthly_debit_amount": "500000.00",10 "iso_currency_code": "USD",11 "request_id": "saKrIBuEB9qJZno"12}
Was this helpful?
/transfer/create
Create a transfer
Use the /transfer/create
endpoint to initiate a new transfer.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
access_token
for the account that will be debited or credited.account_id
account_id
corresponding to the end-user account that will be debited or credited.authorization_id
amount
description
description
field must be "Retry"
to indicate that it's a retry of a previously returned transfer. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code R01
or R09
may be retried. For a full listing of ACH return codes, see Transfer errors.15
metadata
test_clock_id
sandbox
environment. If provided, the transfer
is created at the virtual_time
on the provided test_clock
.1const request: TransferCreateRequest = {2 amount: '12.34',3 description: 'payment',4 access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',5 account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',6 authorization_id: '231h012308h3101z21909sw',7};8try {9 const response = await client.transferCreate(request);10 const transfer = response.data.transfer;11} catch (error) {12 // handle error13}
Response fields and example
transfer
id
authorization_id
ach_class
"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 Internetccd
, ppd
, tel
, web
account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
type
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
, credit
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
amount
description
created
2006-01-02T15:04:05Z
date-time
status
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.pending
, posted
, settled
, cancelled
, failed
, returned
sweep_status
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)null
, unswept
, swept
, swept_settled
, return_swept
network
For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get
before calling /transfer/authorization/create
.ach
, same-day-ach
, rtp
cancellable
true
, you can still cancel this transfer.failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
metadata
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
date
originator_client_id
refunds
id
transfer_id
amount
status
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.pending
, posted
, cancelled
, failed
, settled
, returned
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
expected_sweep _settlement_schedule
returned
. Only applies to ACH debit transfers.sweep_settlement_date
date
swept_settled_amount
sweep_settlement_date
.credit_funds_source
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 Plaidsweep
, prefunded_rtp_credits
, prefunded_ach_credits
, null
request_id
1{2 "transfer": {3 "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",4 "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586",5 "ach_class": "ppd",6 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",7 "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",8 "type": "credit",9 "user": {10 "legal_name": "Anne Charleston",11 "phone_number": "510-555-0128",12 "email_address": "acharleston@email.com",13 "address": {14 "street": "123 Main St.",15 "city": "San Francisco",16 "region": "CA",17 "postal_code": "94053",18 "country": "US"19 }20 },21 "amount": "12.34",22 "description": "payment",23 "created": "2020-08-06T17:27:15Z",24 "refunds": [],25 "status": "pending",26 "network": "ach",27 "cancellable": true,28 "guarantee_decision": null,29 "guarantee_decision_rationale": null,30 "failure_reason": null,31 "metadata": {32 "key1": "value1",33 "key2": "value2"34 },35 "origination_account_id": "",36 "iso_currency_code": "USD",37 "standard_return_window": "2023-08-07",38 "unauthorized_return_window": "2023-10-07",39 "expected_settlement_date": "2023-08-04",40 "originator_client_id": "569ed2f36b3a3a021713abc1",41 "recurring_transfer_id": null,42 "credit_funds_source": "sweep"43 },44 "request_id": "saKrIBuEB9qJZno"45}
Was this helpful?
/transfer/cancel
Cancel a transfer
Use the /transfer/cancel
endpoint to cancel a transfer. A transfer is eligible for cancellation if the cancellable
property returned by /transfer/get
is true
.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.transfer_id
1const request: TransferCancelRequest = {2 transfer_id: '123004561178933',3};4try {5 const response = await plaidClient.transferCancel(request);6 const request_id = response.data.request_id;7} catch (error) {8 // handle error9}
Response fields and example
request_id
1{2 "request_id": "saKrIBuEB9qJZno"3}
Was this helpful?
/transfer/get
Retrieve a transfer
The /transfer/get
endpoint fetches information about the transfer corresponding to the given transfer_id
.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.transfer_id
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 error9}
Response fields and example
transfer
id
authorization_id
ach_class
"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 Internetccd
, ppd
, tel
, web
account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
type
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
, credit
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
amount
description
created
2006-01-02T15:04:05Z
date-time
status
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.pending
, posted
, settled
, cancelled
, failed
, returned
sweep_status
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)null
, unswept
, swept
, swept_settled
, return_swept
network
For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get
before calling /transfer/authorization/create
.ach
, same-day-ach
, rtp
cancellable
true
, you can still cancel this transfer.failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
metadata
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
date
originator_client_id
refunds
id
transfer_id
amount
status
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.pending
, posted
, cancelled
, failed
, settled
, returned
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
expected_sweep _settlement_schedule
returned
. Only applies to ACH debit transfers.sweep_settlement_date
date
swept_settled_amount
sweep_settlement_date
.credit_funds_source
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 Plaidsweep
, prefunded_rtp_credits
, prefunded_ach_credits
, null
request_id
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 },47 "request_id": "saKrIBuEB9qJZno"48}
Was this helpful?
/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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.start_date
2019-12-06T22:35:49Z
)date-time
end_date
2019-12-06T22:35:49Z
)date-time
count
1
25
25
offset
0
0
originator_client_id
funding_account_id
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 transfers13 }14} catch (error) {15 // handle error16}
Response fields and example
transfers
id
authorization_id
ach_class
"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 Internetccd
, ppd
, tel
, web
account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
type
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
, credit
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
amount
description
created
2006-01-02T15:04:05Z
date-time
status
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.pending
, posted
, settled
, cancelled
, failed
, returned
sweep_status
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)null
, unswept
, swept
, swept_settled
, return_swept
network
For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded 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/eligibility/get
before calling /transfer/authorization/create
.ach
, same-day-ach
, rtp
cancellable
true
, you can still cancel this transfer.failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
metadata
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
date
originator_client_id
refunds
id
transfer_id
amount
status
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.pending
, posted
, cancelled
, failed
, settled
, returned
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
expected_sweep _settlement_schedule
returned
. Only applies to ACH debit transfers.sweep_settlement_date
date
swept_settled_amount
sweep_settlement_date
.credit_funds_source
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 Plaidsweep
, prefunded_rtp_credits
, prefunded_ach_credits
, null
request_id
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 }48 ],49 "request_id": "saKrIBuEB9qJZno"50}
Was this helpful?
/transfer/event/list
List transfer events
Use the /transfer/event/list
endpoint to get a list of transfer events based on specified filter criteria.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.start_date
2019-12-06T22:35:49Z
)date-time
end_date
2019-12-06T22:35:49Z
)date-time
transfer_id
account_id
transfer_type
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
, null
event_types
pending
, cancelled
, failed
, posted
, settled
, returned
, swept
, swept_settled
, return_swept
, sweep.pending
, sweep.posted
, sweep.settled
, sweep.returned
, sweep.failed
sweep_id
count
count
, the most recent events will be returned.25
25
1
offset
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.0
0
originator_client_id
funding_account_id
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 events17 }18} catch (error) {19 // handle error20}
Response fields and example
transfer_events
event_id
0
timestamp
2006-01-02T15:04:05Z
.date-time
event_type
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.pending
, cancelled
, failed
, posted
, settled
, returned
, swept
, swept_settled
, return_swept
, sweep.pending
, sweep.posted
, sweep.settled
, sweep.returned
, sweep.failed
account_id
funding_account_id
transfer_id
null
for Plaid Ledger Sweep events.transfer_type
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.debit
, credit
transfer_amount
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
sweep_id
sweep_amount
swept
or return_swept
for this transfer (decimal string with two digits of precision e.g. "-5.50").refund_id
originator_client_id
request_id
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}
Was this helpful?
/transfer/metrics/get
Get transfer product usage metrics
Use the /transfer/metrics/get
endpoint to view your transfer product usage metrics.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.originator_client_id
client_id
is a third-party sender (TPS).1const request: TransferMetricsGetRequest = {2 originator_client_id: '61b8f48ded273e001aa8db6d',3};45try {6 const response = await client.transferMetricsGet(request);7} catch (error) {8 // handle error9}
Response fields and example
request_id
daily_debit_transfer _volume
daily_credit_transfer _volume
monthly_transfer _volume
monthly_debit _transfer_volume
monthly_credit _transfer_volume
iso_currency_code
1{2 "daily_debit_transfer_volume": "1234.56",3 "daily_credit_transfer_volume": "567.89",4 "monthly_transfer_volume": "12345.67",5 "monthly_debit_transfer_volume": "10000.00",6 "monthly_credit_transfer_volume": "2345.67",7 "iso_currency_code": "USD",8 "request_id": "saKrIBuEB9qJZno"9}
Was this helpful?
/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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.after_id
event_id
fetched via the sync endpoint, or 0 initially.0
count
25
1
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 events10 }11} catch (error) {12 // handle error13}
Response fields and example
transfer_events
event_id
0
timestamp
2006-01-02T15:04:05Z
.date-time
event_type
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.pending
, cancelled
, failed
, posted
, settled
, returned
, swept
, swept_settled
, return_swept
, sweep.pending
, sweep.posted
, sweep.settled
, sweep.returned
, sweep.failed
account_id
funding_account_id
transfer_id
null
for Plaid Ledger Sweep events.transfer_type
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.debit
, credit
transfer_amount
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
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
sweep_id
sweep_amount
swept
or return_swept
for this transfer (decimal string with two digits of precision e.g. "-5.50").refund_id
originator_client_id
request_id
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}
Was this helpful?
/transfer/sweep/get
Retrieve a sweep
The /transfer/sweep/get
endpoint fetches a sweep corresponding to the given sweep_id
.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.sweep_id
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 error9}
Response fields and example
sweep
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
funding_account_id
created
date-time
amount
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
settled
date
status
"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 failedpending
, posted
, settled
, returned
, failed
, null
trigger
"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.manual
, incoming
, balance_threshold
, automatic_aggregate
description
request_id
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 },11 "request_id": "saKrIBuEB9qJZno"12}
Was this helpful?
/transfer/sweep/list
List sweeps
The /transfer/sweep/list
endpoint fetches sweeps matching the given filters.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.start_date
date-time
end_date
date-time
count
1
25
25
offset
0
0
amount
status
"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 failedpending
, posted
, settled
, returned
, failed
, null
originator_client_id
funding_account_id
funding_account_id
.transfer_id
transfer_id
.trigger
"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.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 sweeps12 }13} catch (error) {14 // handle error15}
Response fields and example
sweeps
id
funding_account_id
created
date-time
amount
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
settled
date
status
"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 failedpending
, posted
, settled
, returned
, failed
, null
trigger
"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.manual
, incoming
, balance_threshold
, automatic_aggregate
description
request_id
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": null12 }13 ],14 "request_id": "saKrIBuEB9qJZno"15}
Was this helpful?
/transfer/intent/create
Create a transfer intent object to invoke the Transfer UI
Use the /transfer/intent/create
endpoint to generate a transfer intent object and invoke the Transfer UI.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
funding_account_id
s in the Accounts page of your Plaid Dashboard, under the "Account ID" column.mode
PAYMENT
: Transfers funds from an end user's account to your business account.DISBURSEMENT
: Transfers funds from your business account to an end user's account.PAYMENT
, DISBURSEMENT
network
same-day-ach
.For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.ach
, same-day-ach
same-day-ach
amount
description
1
8
ach_class
"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 Internetccd
, ppd
, tel
, web
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
metadata
iso_currency_code
1const request: TransferIntentCreateRequest = {2 account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',3 mode: 'PAYMENT'4 amount: '12.34',5 description: 'Desc',6 ach_class: 'ppd',7 origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359',8 user: {9 legal_name: 'Anne Charleston',10 },11};1213try {14 const response = await client.transferIntentCreate(request);15} catch (error) {16 // handle error17}
Response fields and example
transfer_intent
id
created
2006-01-02T15:04:05Z
.date-time
status
PENDING
: The transfer intent is pending.
SUCCEEDED
: The transfer intent was successfully created.
FAILED
: The transfer intent was unable to be created.PENDING
, SUCCEEDED
, FAILED
account_id
account_id
corresponding to the end-user account that will be debited or credited. Returned only if account_id
was set on intent creation.funding_account_id
amount
mode
PAYMENT
: Transfers funds from an end user's account to your business account.DISBURSEMENT
: Transfers funds from your business account to an end user's account.PAYMENT
, DISBURSEMENT
network
same-day-ach
.For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.ach
, same-day-ach
same-day-ach
ach_class
"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 Internetccd
, ppd
, tel
, web
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
description
metadata
iso_currency_code
request_id
1{2 "transfer_intent": {3 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",4 "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",5 "ach_class": "ppd",6 "amount": "12.34",7 "iso_currency_code": "USD",8 "created": "2020-08-06T17:27:15Z",9 "description": "Desc",10 "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",11 "metadata": {12 "key1": "value1",13 "key2": "value2"14 },15 "mode": "PAYMENT",16 "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",17 "status": "PENDING",18 "user": {19 "address": {20 "street": "100 Market Street",21 "city": "San Francisco",22 "region": "CA",23 "postal_code": "94103",24 "country": "US"25 },26 "email_address": "acharleston@email.com",27 "legal_name": "Anne Charleston",28 "phone_number": "123-456-7890"29 }30 },31 "request_id": "saKrIBuEB9qJZno"32}
Was this helpful?
/transfer/intent/get
Retrieve more information about a transfer intent
Use the /transfer/intent/get
endpoint to retrieve more information about a transfer intent.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.transfer_intent_id
1const request: TransferIntentGetRequest = {2 transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',3};45try {6 const response = await client.transferIntentGet(request);7} catch (error) {8 // handle error9}
Response fields and example
transfer_intent
id
created
2006-01-02T15:04:05Z
.date-time
status
PENDING
: The transfer intent is pending.
SUCCEEDED
: The transfer intent was successfully created.
FAILED
: The transfer intent was unable to be created.PENDING
, SUCCEEDED
, FAILED
transfer_id
failure_reason
failed
. Null otherwise.error_type
error_code
error_message
authorization_decision
APPROVED
– The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The decision_rationale
field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update to re-authenticate your user when decision_rationale.code
is ITEM_LOGIN_REQUIRED
). Refer to the code
field in the decision_rationale
object for details.DECLINED
– Plaid reviewed the proposed transfer and declined processing. Refer to the code
field in the decision_rationale
object for details.APPROVED
, DECLINED
authorization _decision_rationale
declined
decisions, and may or may not be null for approved
decisions.code
If the
rationale_code
is null
, the transfer passed the authorization check. Any non-
null
value for an approved
transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an approved
transfer are:MANUALLY_VERIFIED_ITEM
– Item created via same-day micro deposits, limited information available. ITEM_LOGIN_REQUIRED
– Unable to collect the account information due to Item staleness. Can be resolved by using Link in update mode. MIGRATED_ACCOUNT_ITEM
- Item created via /transfer/account_migration
endpoint, limited information available.ERROR
– Unable to collect the account information due to an unspecified error.The following codes indicate that the authorization decision was
declined
:NSF
– Transaction likely to result in a return due to insufficient funds. RISK
- Transaction is high-risk. TRANSFER_LIMIT_REACHED
- One or several transfer limits are reached, e.g. monthly transfer limit.NSF
, RISK
, TRANSFER_LIMIT_REACHED
, MANUALLY_VERIFIED_ITEM
, ITEM_LOGIN_REQUIRED
, PAYMENT_PROFILE_LOGIN_REQUIRED
, ERROR
, MIGRATED_ACCOUNT_ITEM
, null
description
account_id
account_id
for the account that will be debited or credited. Returned only if account_id
was set on intent creation.funding_account_id
amount
mode
PAYMENT
: Transfers funds from an end user's account to your business account.DISBURSEMENT
: Transfers funds from your business account to an end user's account.PAYMENT
, DISBURSEMENT
network
same-day-ach
.For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a transfer at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any transfer that is indicated as same-day-ach
and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges. Note that both legs of the transfer will be downgraded if applicable.ach
, same-day-ach
same-day-ach
ach_class
"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 Internetccd
, ppd
, tel
, web
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
description
metadata
iso_currency_code
request_id
1{2 "transfer_intent": {3 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",4 "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359",5 "ach_class": "ppd",6 "amount": "12.34",7 "iso_currency_code": "USD",8 "authorization_decision": "APPROVED",9 "authorization_decision_rationale": null,10 "created": "2019-12-09T17:27:15Z",11 "description": "Desc",12 "failure_reason": null,13 "guarantee_decision": null,14 "guarantee_decision_rationale": null,15 "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",16 "metadata": {17 "key1": "value1",18 "key2": "value2"19 },20 "mode": "DISBURSEMENT",21 "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359",22 "status": "SUCCEEDED",23 "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2",24 "user": {25 "address": {26 "street": "123 Main St.",27 "city": "San Francisco",28 "region": "California",29 "postal_code": "94053",30 "country": "US"31 },32 "email_address": "acharleston@email.com",33 "legal_name": "Anne Charleston",34 "phone_number": "510-555-0128"35 }36 },37 "request_id": "saKrIBuEB9qJZno"38}