Transfer (beta)
API reference for Transfer endpoints and webhooks
Intelligently process transfers between accounts in the US.
Only supported in Plaid's Sandbox and Production environments.
Endpoints | |
---|---|
/transfer/authorization/create | Create a transfer authorization |
/transfer/capabilities/get | Determine RTP eligibility for a Plaid Item |
/transfer/configuration/get | Get transfer product configuration |
/transfer/create | Create a transfer |
/transfer/cancel | Cancel a transfer |
/transfer/get | Retrieve information about a transfer |
/transfer/list | Retrieve a list of transfers and their statuses |
/transfer/metrics/get | Get transfer product usage metrics |
/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 |
/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/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 |
/transfer/refund/create | Create a refund for a transfer |
/transfer/refund/cancel | Cancel a refund |
/transfer/refund/get | Retrieve information about a refund |
/transfer/migrate_account | Create an Item to use with Transfer from known account and routing numbers |
/payment_profile/create | Create a Payment Profile |
/payment_profile/remove | Remove a Payment Profile |
/payment_profile/get | Retrieve the status of a Payment Profile |
/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/questionnaire/create | Generate a Plaid-hosted onboarding UI URL |
See also | |
---|---|
/sandbox/payment_profile/reset_login | Simulate a Payment Profile login invalidation |
/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/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 determine transfer failure risk.
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.device.ip_address
, device.user_agent
are required fields.
For Guarantee, the following fields are required : idempotency_key
, user.phone_number
(optional if email_address
provided), user.email_address
(optional if phone_number
provided), device.ip_address
, device.user_agent
, and user_present
.
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. Required if not using payment_profile_token
.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
payment_profile_token
access_token
.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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, 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
legal_name
phone_number
phone_number
or email_address
must be provided.email_address
phone_number
or email_address
must be provided.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.
Failure to provide this key may result in duplicate charges.
Required for guaranteed ACH customers.
50
user_present
true
; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false
.with_guarantee
false
, Plaid will not offer a guarantee_decision
for this request(Guarantee customers only).true
beacon_session_id
originator_client_id
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
MANUALLY_VERIFIED_ITEM
– Item created via same-day micro deposits, limited information available. Plaid will offer approved
as a transaction decision.ITEM_LOGIN_REQUIRED
– Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved
as a transaction decision.PAYMENT_PROFILE_LOGIN_REQUIRED
- Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved
as a transaction decision.ERROR
– Unable to collect the account information due to an error. Plaid will offer approved
as a transaction decision.NSF
– Transaction likely to result in a return due to insufficient funds. Plaid will offer declined
as a transaction decision.RISK
- Transaction is high-risk. Plaid will offer declined
as a transaction decision.TRANSFER_LIMIT_REACHED
- One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined
as a transaction decision.MIGRATED_ACCOUNT_ITEM
- Item created via /transfer/account_migration
endpoint, limited information available. Plaid will offer approved
as a transaction decision.NSF
, RISK
, TRANSFER_LIMIT_REACHED
, MANUALLY_VERIFIED_ITEM
, ITEM_LOGIN_REQUIRED
, PAYMENT_PROFILE_LOGIN_REQUIRED
, ERROR
, MIGRATED_ACCOUNT_ITEM
description
guarantee_decision
GUARANTEED
or NOT_GUARANTEED
indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale
field. Refer to the code
field in guarantee_decision_rationale
for details.GUARANTEED
, NOT_GUARANTEED
, null
guarantee_decision _rationale
null
unless guarantee_decision
is NOT_GUARANTEED
.code
RETURN_BANK
: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.RETURN_CUSTOMER
: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.GUARANTEE_LIMIT_REACHED
: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.RISK_ESTIMATE_UNAVAILABLE
: A risk estimate is unavailable for this Item.REQUIRED_PARAM_MISSING
: Required fields are missing.RETURN_BANK
, RETURN_CUSTOMER
, GUARANTEE_LIMIT_REACHED
, RISK_ESTIMATE_UNAVAILABLE
, REQUIRED_PARAM_MISSING
description
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
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": "GUARANTEED",8 "guarantee_decision_rationale": null,9 "proposed_transfer": {10 "ach_class": "ppd",11 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",12 "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",13 "type": "credit",14 "user": {15 "legal_name": "Anne Charleston",16 "phone_number": "510-555-0128",17 "email_address": "acharleston@email.com",18 "address": {19 "street": "123 Main St.",20 "city": "San Francisco",21 "region": "CA",22 "postal_code": "94053",23 "country": "US"24 }25 },26 "amount": "12.34",27 "network": "ach",28 "iso_currency_code": "USD",29 "origination_account_id": "",30 "originator_client_id": null31 }32 },33 "request_id": "saKrIBuEB9qJZno"34}
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. Required if not using payment_profile_token
.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.payment_profile_token
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 client_id: '6a65dh3d1h0d1027121ak184',3 originator_client_id: '61b8f48ded273e001aa8db6d'4};56try {7 const response = await client.transferConfigurationGet(request);8} catch (error) {9 // handle error10}
Response fields and example
request_id
max_single_transfer _amount
max_daily_credit _amount
max_daily_debit_amount
max_monthly_amount
iso_currency_code
1{2 "max_single_transfer_amount": "1000.00",3 "max_daily_credit_amount": "50000.00",4 "max_daily_debit_amount": "50000.00",5 "max_monthly_amount": "500000.00",6 "iso_currency_code": "USD",7 "request_id": "saKrIBuEB9qJZno"8}
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. Required if not using payment_profile_token
.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.payment_profile_token
access_token
.authorization_id
amount
description
10
metadata
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
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, 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
guarantee_decision
GUARANTEED
or NOT_GUARANTEED
indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale
field. Refer to the code
field in guarantee_decision_rationale
for details.GUARANTEED
, NOT_GUARANTEED
, null
guarantee_decision _rationale
null
unless guarantee_decision
is NOT_GUARANTEED
.code
RETURN_BANK
: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.RETURN_CUSTOMER
: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.GUARANTEE_LIMIT_REACHED
: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.RISK_ESTIMATE_UNAVAILABLE
: A risk estimate is unavailable for this Item.REQUIRED_PARAM_MISSING
: Required fields are missing.RETURN_BANK
, RETURN_CUSTOMER
, GUARANTEE_LIMIT_REACHED
, RISK_ESTIMATE_UNAVAILABLE
, REQUIRED_PARAM_MISSING
description
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
pending
. Only set for ACH transfers and is null
for non-ACH transfers. This will be of the form YYYY-MM-DD.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.
cancelled
: The refund was cancelled by the client.
failed
: The refund failed or was returned.pending
, posted
, cancelled
, failed
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
request_id
1{2 "transfer": {3 "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",4 "ach_class": "ppd",5 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",6 "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",7 "type": "credit",8 "user": {9 "legal_name": "Anne Charleston",10 "phone_number": "510-555-0128",11 "email_address": "acharleston@email.com",12 "address": {13 "street": "123 Main St.",14 "city": "San Francisco",15 "region": "CA",16 "postal_code": "94053",17 "country": "US"18 }19 },20 "amount": "12.34",21 "description": "payment",22 "created": "2020-08-06T17:27:15Z",23 "refunds": [],24 "status": "pending",25 "network": "ach",26 "cancellable": true,27 "guarantee_decision": "GUARANTEED",28 "guarantee_decision_rationale": null,29 "failure_reason": null,30 "metadata": {31 "key1": "value1",32 "key2": "value2"33 },34 "origination_account_id": "",35 "iso_currency_code": "USD",36 "standard_return_window": "2020-08-07",37 "unauthorized_return_window": "2020-10-07",38 "expected_settlement_date": "2020-08-04",39 "originator_client_id": "569ed2f36b3a3a021713abc1",40 "recurring_transfer_id": null41 },42 "request_id": "saKrIBuEB9qJZno"43}
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
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, 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
guarantee_decision
GUARANTEED
or NOT_GUARANTEED
indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale
field. Refer to the code
field in guarantee_decision_rationale
for details.GUARANTEED
, NOT_GUARANTEED
, null
guarantee_decision _rationale
null
unless guarantee_decision
is NOT_GUARANTEED
.code
RETURN_BANK
: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.RETURN_CUSTOMER
: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.GUARANTEE_LIMIT_REACHED
: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.RISK_ESTIMATE_UNAVAILABLE
: A risk estimate is unavailable for this Item.REQUIRED_PARAM_MISSING
: Required fields are missing.RETURN_BANK
, RETURN_CUSTOMER
, GUARANTEE_LIMIT_REACHED
, RISK_ESTIMATE_UNAVAILABLE
, REQUIRED_PARAM_MISSING
description
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
pending
. Only set for ACH transfers and is null
for non-ACH transfers. This will be of the form YYYY-MM-DD.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.
cancelled
: The refund was cancelled by the client.
failed
: The refund failed or was returned.pending
, posted
, cancelled
, failed
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
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 "metadata": {18 "key1": "value1",19 "key2": "value2"20 },21 "network": "ach",22 "origination_account_id": "",23 "originator_client_id": null,24 "refunds": [],25 "status": "pending",26 "type": "credit",27 "iso_currency_code": "USD",28 "standard_return_window": "2020-08-07",29 "unauthorized_return_window": "2020-10-07",30 "expected_settlement_date": "2020-08-04",31 "user": {32 "email_address": "acharleston@email.com",33 "legal_name": "Anne Charleston",34 "phone_number": "510-555-0128",35 "address": {36 "street": "123 Main St.",37 "city": "San Francisco",38 "region": "CA",39 "postal_code": "94053",40 "country": "US"41 }42 },43 "recurring_transfer_id": null44 },45 "request_id": "saKrIBuEB9qJZno"46}
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
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, 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
guarantee_decision
GUARANTEED
or NOT_GUARANTEED
indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale
field. Refer to the code
field in guarantee_decision_rationale
for details.GUARANTEED
, NOT_GUARANTEED
, null
guarantee_decision _rationale
null
unless guarantee_decision
is NOT_GUARANTEED
.code
RETURN_BANK
: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.RETURN_CUSTOMER
: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.GUARANTEE_LIMIT_REACHED
: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.RISK_ESTIMATE_UNAVAILABLE
: A risk estimate is unavailable for this Item.REQUIRED_PARAM_MISSING
: Required fields are missing.RETURN_BANK
, RETURN_CUSTOMER
, GUARANTEE_LIMIT_REACHED
, RISK_ESTIMATE_UNAVAILABLE
, REQUIRED_PARAM_MISSING
description
iso_currency_code
standard_return_window
date
unauthorized_return _window
date
expected_settlement _date
pending
. Only set for ACH transfers and is null
for non-ACH transfers. This will be of the form YYYY-MM-DD.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.
cancelled
: The refund was cancelled by the client.
failed
: The refund failed or was returned.pending
, posted
, cancelled
, failed
created
2006-01-02T15:04:05Z
date-time
recurring_transfer_id
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 "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": null45 }46 ],47 "request_id": "saKrIBuEB9qJZno"48}
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_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
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.pending
, cancelled
, failed
, posted
, settled
, returned
, swept
, swept_settled
, return_swept
account_id
funding_account_id
transfer_id
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.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
(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 client_id: '6a65dh3d1h0d1027121ak184',3 originator_client_id: '61b8f48ded273e001aa8db6d'4};56try {7 const response = await client.transferMetricsGet(request);8} catch (error) {9 // handle error10}
Response fields and example
request_id
daily_debit_transfer _volume
daily_credit_transfer _volume
monthly_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 "iso_currency_code": "USD",6 "request_id": "saKrIBuEB9qJZno"7}
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. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see micro-deposit events.
Request fields 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
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.pending
, cancelled
, failed
, posted
, settled
, returned
, swept
, swept_settled
, return_swept
account_id
funding_account_id
transfer_id
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.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
(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
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 },10 "request_id": "saKrIBuEB9qJZno"11}
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
originator_client_id
funding_account_id
funding_account_id
.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
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 "originator_client_id": null11 }12 ],13 "request_id": "saKrIBuEB9qJZno"14}
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
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
require_guarantee
true
, the transfer requires a GUARANTEED
decision by Plaid to proceed (Guarantee customers only).false
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
require_guarantee
true
, the transfer requires a GUARANTEED
decision by Plaid to proceed (Guarantee customers only).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
MANUALLY_VERIFIED_ITEM
– Item created via same-day micro deposits, limited information available. Plaid will offer approved
as a transaction decision.ITEM_LOGIN_REQUIRED
– Unable to collect the account information due to Item staleness. Can be rectified using Link in update mode. Plaid will offer approved
as a transaction decision.PAYMENT_PROFILE_LOGIN_REQUIRED
- Unable to collect the account information due to invalid login when using Payment Profiles. Can be rectified using update mode for Payment Profile. Plaid will offer approved
as a transaction decision.ERROR
– Unable to collect the account information due to an error. Plaid will offer approved
as a transaction decision.NSF
– Transaction likely to result in a return due to insufficient funds. Plaid will offer declined
as a transaction decision.RISK
- Transaction is high-risk. Plaid will offer declined
as a transaction decision.TRANSFER_LIMIT_REACHED
- One or several transfer limits are reached, e.g. monthly transfer limit. Plaid will offer declined
as a transaction decision.MIGRATED_ACCOUNT_ITEM
- Item created via /transfer/account_migration
endpoint, limited information available. Plaid will offer approved
as a transaction decision.NSF
, RISK
, TRANSFER_LIMIT_REACHED
, MANUALLY_VERIFIED_ITEM
, ITEM_LOGIN_REQUIRED
, PAYMENT_PROFILE_LOGIN_REQUIRED
, ERROR
, MIGRATED_ACCOUNT_ITEM
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
require_guarantee
true
, the transfer requires a GUARANTEED
decision by Plaid to proceed (Guarantee customers only).guarantee_decision
GUARANTEED
or NOT_GUARANTEED
indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the guarantee_decision_rationale
field. Refer to the code
field in guarantee_decision_rationale
for details.GUARANTEED
, NOT_GUARANTEED
, null
guarantee_decision _rationale
null
unless guarantee_decision
is NOT_GUARANTEED
.code
RETURN_BANK
: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer.RETURN_CUSTOMER
: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer.GUARANTEE_LIMIT_REACHED
: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer.RISK_ESTIMATE_UNAVAILABLE
: A risk estimate is unavailable for this Item.REQUIRED_PARAM_MISSING
: Required fields are missing.RETURN_BANK
, RETURN_CUSTOMER
, GUARANTEE_LIMIT_REACHED
, RISK_ESTIMATE_UNAVAILABLE
, REQUIRED_PARAM_MISSING
description
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}
Was this helpful?
/transfer/recurring/create
Create a recurring transfer
Use the /transfer/recurring/create
endpoint to initiate a new recurring 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. Required if not using payment_profile_token
.idempotency_key
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a recurring fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single recurring transfer is created.
50
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
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 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, rtp
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
amount
user_present
true
; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be false
.description
test_clock_id
schedule
interval_unit
week
, month
1
interval_count
interval_units
between originations. The recurring interval(before holiday adjustment) is calculated by multiplying interval_unit
and interval_count
.
For instance, to schedule a recurring transfer which originates once every two weeks, set interval_unit
= week
and interval_count
= 2.interval_execution_day
If the
interval_unit
is week
, interval_execution_day
should be an integer from 1 (Monday) to 5 (Friday).If the
interval_unit
is month
, interval_execution_day
should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on.The transfer will be originated on next available banking day if the designated day is a non banking day.
start_date
interval_execution_day
on or after the start_date
.If the first
interval_execution_day
on or after the start date is also the same day that /transfer/recurring/create
was called, the bank may make the first payment on that day, but it is not guaranteed to do so.date
end_date
interval_execution_day
on or before the end_date
.
If the interval_execution_day
between the start date and the end date (inclusive) is also the same day that /transfer/recurring/create
was called, the bank may make a payment on that day, but it is not guaranteed to do so.date
user
legal_name
phone_number
email_address
address
street
city
region
postal_code
country
device
ip_address
user_agent
1const request: TransferRecurringCreateRequest = {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 description: 'payment',9 idempotency_key: '12345',10 schedule: {11 start_date: '2022-10-01',12 end_date: '20223-10-01',13 interval_unit: 'week',14 interval_count: 1,15 interval_execution_day: 516 }17 user: {18 legal_name: 'Anne Charleston',19 },20};2122try {23 const response = await client.transferRecurringCreate(request);24 const recurringTransferId = response.data.recurring_transfer.recurring_transfer_id;25} catch (error) {26 // handle error27}
Response fields and example
recurring_transfer
recurring_transfer_id
created
2006-01-02T15:04:05Z
date-time
next_origination_date
The next transfer origination date after bank holiday adjustment.
date
test_clock_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
amount
status
active
: The recurring transfer is currently active.
cancelled
: The recurring transfer was cancelled by the client or Plaid.
expired
: The recurring transfer has completed all originations according to its recurring schedule.active
, cancelled
, expired
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
network
For transfers submitted as either
ach
or same-day-ach
the cutoff for same-day is 9:30 AM Pacific Time and the cutoff for next-day transfers is 5:30 PM Pacific 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
, rtp
account_id
account_id
corresponding to the end-user account that will be debited or credited.funding_account_id
iso_currency_code
description
transfer_ids
user
legal_name
phone_number
email_address