Virtual Accounts (UK and Europe)

API reference for Virtual Accounts endpoints and webhooks

Manage the entire lifecycle of a payment. For how-to guidance, see the Virtual Accounts documentation.

Endpoints
/wallet/createCreate a virtual account
/wallet/getFetch a virtual account
/wallet/listList all virtual accounts
/wallet/transaction/executeExecute a transaction
/wallet/transaction/getFetch a transaction
/wallet/transaction/listList all transactions
See also
/payment_initiation/payment/reverseRefund a payment from a virtual account
Webhooks
WALLET_TRANSACTION_STATUS_UPDATEThe status of a transaction has changed

Endpoints

=*=*=*=

/wallet/create

Create an e-wallet

Create an e-wallet. The response is the newly created e-wallet object.

wallet/create

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
iso_currency_code
requiredstringrequired, string
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3 
1const request: WalletCreateRequest = {
2  iso_currency_code: isoCurrencyCode,
3};
4try {
5  const response = await plaidClient.walletCreate(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}
wallet/create

Response fields and example

wallet_id
stringstring
A unique ID identifying the e-wallet
balance
objectobject
An object representing the e-wallet balance
iso_currency_code
stringstring
The ISO-4217 currency code of the balance
current
numbernumber
The total amount of funds in the account

Format: double
available
numbernumber
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
objectobject
An object representing the e-wallet account numbers
bacs
nullableobjectnullable, object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobjectnullable, object
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
stringstring
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
stringstring
The ID of the recipient that corresponds to the e-wallet account numbers
status
stringstring
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
4  "balance": {
5    "iso_currency_code": "GBP",
6    "current": 123.12,
7    "available": 100.96
8  },
9  "request_id": "4zlKapIkTm8p5KM",
10  "numbers": {
11    "bacs": {
12      "account": "12345678",
13      "sort_code": "123456"
14    }
15  },
16  "status": "ACTIVE"
17}
=*=*=*=

/wallet/get

Fetch an e-wallet

Fetch an e-wallet. The response includes the current balance.

wallet/get

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
wallet_id
requiredstringrequired, string
The ID of the e-wallet

Min length: 1 
1const request: WalletGetRequest = {
2  wallet_id: walletID,
3};
4try {
5  const response = await plaidClient.walletGet(request);
6  const walletID = response.data.wallet_id;
7  const balance = response.data.balance;
8  const numbers = response.data.numbers;
9  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}
wallet/get

Response fields and example

wallet_id
stringstring
A unique ID identifying the e-wallet
balance
objectobject
An object representing the e-wallet balance
iso_currency_code
stringstring
The ISO-4217 currency code of the balance
current
numbernumber
The total amount of funds in the account

Format: double
available
numbernumber
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
objectobject
An object representing the e-wallet account numbers
bacs
nullableobjectnullable, object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobjectnullable, object
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
stringstring
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
stringstring
The ID of the recipient that corresponds to the e-wallet account numbers
status
stringstring
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
4  "balance": {
5    "iso_currency_code": "GBP",
6    "current": 123.12,
7    "available": 100.96
8  },
9  "request_id": "4zlKapIkTm8p5KM",
10  "numbers": {
11    "bacs": {
12      "account": "12345678",
13      "sort_code": "123456"
14    },
15    "international": {
16      "iban": "GB33BUKB20201555555555",
17      "bic": "BUKBGB22"
18    }
19  },
20  "status": "ACTIVE"
21}
=*=*=*=

/wallet/list

Fetch a list of e-wallets

This endpoint lists all e-wallets in descending order of creation.

wallet/list

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
iso_currency_code
stringstring
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
cursor
stringstring
A base64 value representing the latest e-wallet that has already been requested. Set this to next_cursor received from the previous /wallet/list request. If provided, the response will only contain e-wallets created before that e-wallet. If omitted, the response will contain e-wallets starting from the most recent, and in descending order.

Max length: 1024
count
integerinteger
The number of e-wallets to fetch

Minimum: 1
Maximum: 20
Default: 10 
1const request: WalletListRequest = {
2  iso_currency_code: 'GBP',
3  count: 10,
4};
5try {
6  const response = await plaidClient.walletList(request);
7  const wallets = response.data.wallets;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
wallet/list

Response fields and example

wallets
[object][object]
An array of e-wallets
wallet_id
stringstring
A unique ID identifying the e-wallet
balance
objectobject
An object representing the e-wallet balance
iso_currency_code
stringstring
The ISO-4217 currency code of the balance
current
numbernumber
The total amount of funds in the account

Format: double
available
numbernumber
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
objectobject
An object representing the e-wallet account numbers
bacs
nullableobjectnullable, object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobjectnullable, object
Account numbers using the International Bank Account Number and BIC/SWIFT code format.
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
bic
stringstring
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11
recipient_id
stringstring
The ID of the recipient that corresponds to the e-wallet account numbers
status
stringstring
The status of the wallet.
UNKNOWN: The wallet status is unknown.
ACTIVE: The wallet is active and ready to send money to and receive money from.
CLOSED: The wallet is closed. Any transactions made to or from this wallet will error.

Possible values: UNKNOWN, ACTIVE, CLOSED
next_cursor
stringstring
Cursor used for fetching e-wallets created before the latest e-wallet provided in this response
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "wallets": [
3    {
4      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
5      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
6      "balance": {
7        "iso_currency_code": "GBP",
8        "current": 123.12,
9        "available": 100.96
10      },
11      "numbers": {
12        "bacs": {
13          "account": "12345678",
14          "sort_code": "123456"
15        }
16      },
17      "status": "ACTIVE"
18    },
19    {
20      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a999",
21      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f7",
22      "balance": {
23        "iso_currency_code": "EUR",
24        "current": 456.78,
25        "available": 100.96
26      },
27      "numbers": {
28        "international": {
29          "iban": "GB22HBUK40221241555626",
30          "bic": "HBUKGB4B"
31        }
32      },
33      "status": "ACTIVE"
34    }
35  ],
36  "request_id": "4zlKapIkTm8p5KM"
37}
=*=*=*=

/wallet/transaction/execute

Execute a transaction using an e-wallet

Execute a transaction using the specified e-wallet. Specify the e-wallet to debit from, the counterparty to credit to, the idempotency key to prevent duplicate transactions, the amount and reference for the transaction. Transactions will settle in seconds to several days, depending on the underlying payment rail.

wallet/transaction/execute

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
idempotency_key
requiredstringrequired, string
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.

Max length: 128
Min length: 1
wallet_id
requiredstringrequired, string
The ID of the e-wallet to debit from

Min length: 1
counterparty
requiredobjectrequired, object
An object representing the e-wallet transaction's counterparty
name
requiredstringrequired, string
The name of the counterparty

Min length: 1
numbers
requiredobjectrequired, object
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
objectobject
The account number and sort code of the counterparty's account
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
objectobject
International Bank Account Number for a Wallet Transaction
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
objectobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
required[string]required, [string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
requiredstringrequired, string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
requiredstringrequired, string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
requiredstringrequired, string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
stringstring
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
amount
requiredobjectrequired, object
The amount and currency of a transaction
iso_currency_code
requiredstringrequired, string
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
requirednumberrequired, number
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
reference
requiredstringrequired, string
A reference for the transaction. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Ensure that the reference field is unique for each transaction.

Max length: 18
Min length: 6
originating_fund_source
objectobject
The original source of the funds. This field is required by local regulation for certain businesses (e.g. money remittance) to send payouts to recipients in the EU and UK.
full_name
requiredstringrequired, string
The full name associated with the source of the funds.
address
requiredobjectrequired, object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
required[string]required, [string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
requiredstringrequired, string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
requiredstringrequired, string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
requiredstringrequired, string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
account_number
requiredstringrequired, string
The account number from which the funds are sourced.
bic
requiredstringrequired, string
The Business Identifier Code, also known as SWIFT code, for this bank account.

Min length: 8
Max length: 11 
1const request: WalletTransactionExecuteRequest = {
2  wallet_id: walletID,
3  counterparty: {
4    name: 'Test',
5    numbers: {
6      bacs: {
7        account: '12345678',
8        sort_code: '123456',
9      },
10    },
11  },
12  amount: {
13    value: 1,
14    iso_currency_code: 'GBP',
15  },
16  reference: 'transaction ABC123',
17  idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753',
18};
19try {
20  const response = await plaidClient.walletTransactionExecute(request);
21  const transactionID = response.data.transaction_id;
22  const status = response.data.status;
23} catch (error) {
24  // handle error
25}
wallet/transaction/execute

Response fields and example

transaction_id
stringstring
A unique ID identifying the transaction
status
stringstring
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transaction_id": "wallet-transaction-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
3  "status": "EXECUTED",
4  "request_id": "4zlKapIkTm8p5KM"
5}
=*=*=*=

/wallet/transaction/get

Fetch an e-wallet transaction

Fetch a specific e-wallet transaction

wallet/transaction/get

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transaction_id
requiredstringrequired, string
The ID of the transaction to fetch

Min length: 1 
1const request: WalletTransactionGetRequest = {
2  transaction_id: transactionID,
3};
4try {
5  const response = await plaidClient.walletTransactionGet(request);
6  const transactionID = response.data.transaction_id;
7  const reference = response.data.reference;
8  const type = response.data.type;
9  const amount = response.data.amount;
10  const counterparty = response.data.counterparty;
11  const status = response.data.status;
12  const createdAt = response.created_at;
13} catch (error) {
14  // handle error
15}
wallet/transaction/get

Response fields and example

transaction_id
stringstring
A unique ID identifying the transaction
wallet_id
stringstring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
reference
stringstring
A reference for the transaction
type
stringstring
The type of the transaction. The supported transaction types that are returned are: BANK_TRANSFER: a transaction which credits an e-wallet through an external bank transfer.
PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty.
PIS_PAY_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints.
REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs.
FUNDS_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account.
RETURN: an automated transaction where a debit transaction was reversed and money moved back to originating account.
RECALL: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND, FUNDS_SWEEP, RETURN, RECALL
scheme
nullablestringnullable, string
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND.
FASTER_PAYMENTS: The standard payment scheme within the UK.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment to a beneficiary within the SEPA area.

Possible values: null, FASTER_PAYMENTS, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
amount
objectobject
The amount and currency of a transaction
iso_currency_code
stringstring
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
numbernumber
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
counterparty
objectobject
An object representing the e-wallet transaction's counterparty
name
stringstring
The name of the counterparty

Min length: 1
numbers
objectobject
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullableobjectnullable, object
The account number and sort code of the counterparty's account
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobjectnullable, object
International Bank Account Number for a Wallet Transaction
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobjectnullable, object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string][string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
stringstring
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
stringstring
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
stringstring
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
nullablestringnullable, string
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
status
stringstring
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
created_at
stringstring
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
last_status_update
stringstring
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestringnullable, string
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS_PAY_IN and REFUND.
failure_reason
nullablestringnullable, string
The error code of a failed transaction. Error codes include: EXTERNAL_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown.

Possible values: EXTERNAL_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN
error
nullableobjectnullable, object
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
stringstring
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR, CHECK_REPORT_ERROR, CONSUMER_REPORT_ERROR
error_code
stringstring
The particular error code. Safe for programmatic use.
error_code_reason
nullablestringnullable, string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
stringstring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestringnullable, string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
stringstring
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
arrayarray
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableintegernullable, integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
stringstring
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestringnullable, string
Suggested steps for resolving the error
related_transactions
[object][object]
A list of wallet transactions that this transaction is associated with, if any.
id
stringstring
The ID of the related transaction.
type
stringstring
The type of the transaction.

Possible values: PAYOUT, RETURN, REFUND, FUNDS_SWEEP
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
4  "type": "PAYOUT",
5  "reference": "Payout 99744",
6  "amount": {
7    "iso_currency_code": "GBP",
8    "value": 123.12
9  },
10  "status": "EXECUTED",
11  "created_at": "2020-12-02T21:14:54Z",
12  "last_status_update": "2020-12-02T21:15:01Z",
13  "counterparty": {
14    "numbers": {
15      "bacs": {
16        "account": "31926819",
17        "sort_code": "601613"
18      }
19    },
20    "name": "John Smith"
21  },
22  "request_id": "4zlKapIkTm8p5KM",
23  "related_transactions": [
24    {
25      "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2",
26      "type": "RETURN"
27    }
28  ]
29}
=*=*=*=

/wallet/transaction/list

List e-wallet transactions

This endpoint lists the latest transactions of the specified e-wallet. Transactions are returned in descending order by the created_at time.

wallet/transaction/list

Request fields

client_id
stringstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
stringstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
wallet_id
requiredstringrequired, string
The ID of the e-wallet to fetch transactions from

Min length: 1
cursor
stringstring
A value representing the latest transaction to be included in the response. Set this from next_cursor received in the previous /wallet/transaction/list request. If provided, the response will only contain that transaction and transactions created before it. If omitted, the response will contain transactions starting from the most recent, and in descending order by the created_at time.

Max length: 256
count
integerinteger
The number of transactions to fetch

Minimum: 1
Maximum: 200
Default: 10
options
objectobject
Additional wallet transaction options
start_time
stringstring
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date.

Format: date-time
end_time
stringstring
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date.

Format: date-time 
1const request: WalletTransactionListRequest = {
2  wallet_id: walletID,
3  count: 10,
4};
5try {
6  const response = await plaidClient.walletTransactionList(request);
7  const transactions = response.data.transactions;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
wallet/transaction/list

Response fields and example

transactions
[object][object]
An array of transactions of an e-wallet, associated with the given wallet_id
transaction_id
stringstring
A unique ID identifying the transaction
wallet_id
stringstring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
reference
stringstring
A reference for the transaction
type
stringstring
The type of the transaction. The supported transaction types that are returned are: BANK_TRANSFER: a transaction which credits an e-wallet through an external bank transfer.
PAYOUT: a transaction which debits an e-wallet by disbursing funds to a counterparty.
PIS_PAY_IN: a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the Payment Initiation endpoints.
REFUND: a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's PIS APIs.
FUNDS_SWEEP: an automated transaction which debits funds from an e-wallet to a designated client-owned account.
RETURN: an automated transaction where a debit transaction was reversed and money moved back to originating account.
RECALL: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND, FUNDS_SWEEP, RETURN, RECALL
scheme
nullablestringnullable, string
The payment scheme used to execute this transaction. This is present only for transaction types PAYOUT and REFUND.
FASTER_PAYMENTS: The standard payment scheme within the UK.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment to a beneficiary within the SEPA area.

Possible values: null, FASTER_PAYMENTS, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
amount
objectobject
The amount and currency of a transaction
iso_currency_code
stringstring
An ISO-4217 currency code, used with e-wallets and transactions.

Possible values: GBP, EUR
Min length: 3
Max length: 3
value
numbernumber
The amount of the transaction. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
counterparty
objectobject
An object representing the e-wallet transaction's counterparty
name
stringstring
The name of the counterparty

Min length: 1
numbers
objectobject
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullableobjectnullable, object
The account number and sort code of the counterparty's account
account
stringstring
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
stringstring
The 6-character sort code of the account.

Min length: 6
Max length: 6
international
nullableobjectnullable, object
International Bank Account Number for a Wallet Transaction
iban
stringstring
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobjectnullable, object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[string][string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
stringstring
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
stringstring
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
stringstring
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
date_of_birth
nullablestringnullable, string
The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

Format: date
status
stringstring
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
created_at
stringstring
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
last_status_update
stringstring
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestringnullable, string
The payment id that this transaction is associated with, if any. This is present only for transaction types PIS_PAY_IN and REFUND.
failure_reason
nullablestringnullable, string
The error code of a failed transaction. Error codes include: EXTERNAL_SYSTEM: The transaction was declined by an external system. EXPIRED: The transaction request has expired. CANCELLED: The transaction request was rescinded. INVALID: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. UNKNOWN: The transaction was unsuccessful, but the exact cause is unknown.

Possible values: EXTERNAL_SYSTEM, EXPIRED, CANCELLED, INVALID, UNKNOWN
error
nullableobjectnullable, object
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
stringstring
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR, CHECK_REPORT_ERROR, CONSUMER_REPORT_ERROR
error_code
stringstring
The particular error code. Safe for programmatic use.
error_code_reason
nullablestringnullable, string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
stringstring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestringnullable, string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
stringstring
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
arrayarray
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableintegernullable, integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
stringstring
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestringnullable, string
Suggested steps for resolving the error
related_transactions
[object][object]
A list of wallet transactions that this transaction is associated with, if any.
id
stringstring
The ID of the related transaction.
type
stringstring
The type of the transaction.

Possible values: PAYOUT, RETURN, REFUND, FUNDS_SWEEP
next_cursor
stringstring
The value that, when used as the optional cursor parameter to /wallet/transaction/list, will return the corresponding transaction as its first entry.
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "next_cursor": "YWJjMTIzIT8kKiYoKSctPUB",
3  "transactions": [
4    {
5      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
6      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
7      "type": "PAYOUT",
8      "reference": "Payout 99744",
9      "amount": {
10        "iso_currency_code": "GBP",
11        "value": 123.12
12      },
13      "status": "EXECUTED",
14      "created_at": "2020-12-02T21:14:54Z",
15      "last_status_update": "2020-12-02T21:15:01Z",
16      "counterparty": {
17        "numbers": {
18          "bacs": {
19            "account": "31926819",
20            "sort_code": "601613"
21          }
22        },
23        "name": "John Smith"
24      },
25      "related_transactions": [
26        {
27          "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2",
28          "type": "RETURN"
29        }
30      ]
31    },
32    {
33      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
34      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
35      "type": "PAYOUT",
36      "reference": "Payout 99744",
37      "amount": {
38        "iso_currency_code": "EUR",
39        "value": 456.78
40      },
41      "status": "EXECUTED",
42      "created_at": "2020-12-02T21:14:54Z",
43      "last_status_update": "2020-12-02T21:15:01Z",
44      "counterparty": {
45        "numbers": {
46          "international": {
47            "iban": "GB33BUKB20201555555555"
48          }
49        },
50        "name": "John Smith"
51      },
52      "related_transactions": []
53    }
54  ],
55  "request_id": "4zlKapIkTm8p5KM"
56}

Webhooks

Updates are sent to indicate that the status of transaction has changed. All virtual account webhooks have a webhook_type of WALLET.

=*=*=*=

WALLET_TRANSACTION_STATUS_UPDATE

Fired when the status of a wallet transaction has changed.

Properties

webhook_type
stringstring
WALLET
webhook_code
stringstring
WALLET_TRANSACTION_STATUS_UPDATE
transaction_id
stringstring
The transaction_id for the wallet transaction being updated
payment_id
stringstring
The payment_id associated with the transaction. This will be present in case of REFUND and PIS_PAY_IN.
wallet_id
stringstring
The EMI (E-Money Institution) wallet that this payment is associated with. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
new_status
stringstring
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
old_status
stringstring
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.

Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
timestamp
stringstring
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
error
objectobject
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
stringstring
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR, CHECK_REPORT_ERROR, CONSUMER_REPORT_ERROR
error_code
stringstring
The particular error code. Safe for programmatic use.
error_code_reason
stringstring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
stringstring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
stringstring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
stringstring
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
arrayarray
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integerinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
stringstring
The URL of a Plaid documentation page with more information about the error
suggested_action
stringstring
Suggested steps for resolving the error
environment
stringstring
The Plaid environment the webhook was sent from

Possible values: sandbox, production
1{
2  "webhook_type": "WALLET",
3  "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4  "transaction_id": "wallet-transaction-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
5  "payment_id": "payment-id-production-feca8a7a-5591-4aef-9297-f3062bb735d3",
6  "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88",
7  "new_status": "SETTLED",
8  "old_status": "INITIATED",
9  "timestamp": "2017-09-14T14:42:19.350Z",
10  "environment": "production"
11}