Virtual Accounts (UK and Europe)

API reference for Virtual Accounts endpoints and webhooks

Manage the entire lifecycle of a payment.

Virtual account functionality is currently supported only in Production.

Endpoints
/wallet/getFetch a virtual account
/wallet/listList all virtual accounts
/wallet/transaction/executeExecute a transaction
/wallet/transaction/getFetch a transaction
/wallet/transactions/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/get

Fetch an e-wallet

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

wallet/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
wallet_id
requiredstring
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} catch (error) {
10  // handle error
11}
wallet/get

Response fields and example

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

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullable 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
string
The account number of the account. Maximum of 10 characters.

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

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

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

Min length: 8
Max length: 11
recipient_id
string
The ID of the recipient that corresponds to the e-wallet account numbers
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "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  },
8  "request_id": "4zlKapIkTm8p5KM",
9  "numbers": {
10    "bacs": {
11      "account": "12345678",
12      "sort_code": "123456"
13    },
14    "international": {
15      "iban": "GB33BUKB20201555555555",
16      "bic": "BUKBGB22"
17    }
18  }
19}

/wallet/list

Fetch a list of e-wallets

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

wallet/list

Request fields and example

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

Possible values: GBP, EUR
Min length: 3
Max length: 3
cursor
string
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: 256
count
integer
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]
An array of e-wallets
wallet_id
string
A unique ID identifying the e-wallet
balance
object
An object representing the e-wallet balance
iso_currency_code
string
The ISO-4217 currency code of the balance
current
number
The total amount of funds in the account

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullable 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
string
The account number of the account. Maximum of 10 characters.

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

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

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

Min length: 8
Max length: 11
recipient_id
string
The ID of the recipient that corresponds to the e-wallet account numbers
next_cursor
string
Cursor used for fetching e-wallets created before the latest e-wallet provided in this response
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "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      },
10      "numbers": {
11        "bacs": {
12          "account": "12345678",
13          "sort_code": "123456"
14        }
15      }
16    },
17    {
18      "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a999",
19      "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f7",
20      "balance": {
21        "iso_currency_code": "EUR",
22        "current": 456.78
23      },
24      "numbers": {
25        "international": {
26          "iban": "GB22HBUK40221241555626",
27          "bic": "HBUKGB4B"
28        }
29      }
30    }
31  ],
32  "request_id": "4zlKapIkTm8p5KM"
33}

/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 and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
idempotency_key
requiredstring
A random key provided by the client, per unique 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
requiredstring
The ID of the e-wallet to debit from

Min length: 1
counterparty
requiredobject
An object representing the e-wallet transaction's counterparty
name
requiredstring
The name of the counterparty

Min length: 1
numbers
requiredobject
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
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
string
The account number of the account. Maximum of 10 characters.

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

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

Min length: 15
Max length: 34
amount
requiredobject
The amount and currency of a transaction
iso_currency_code
requiredstring
An ISO-4217 currency code, used with e-wallets and transactions.

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

Format: double
Minimum: 1
reference
requiredstring
A reference for the transaction. This must be an alphanumeric string with at most 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: 1 
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
string
A unique ID identifying the transaction
status
string
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
string
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 and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
transaction_id
requiredstring
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
string
A unique ID identifying the transaction
reference
string
A reference for the transaction
type
string
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 initated payment made through Plaid's PIS APIs.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND
amount
object
The amount and currency of a transaction
iso_currency_code
string
An ISO-4217 currency code, used with e-wallets and transactions.

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

Format: double
Minimum: 1
counterparty
object
An object representing the e-wallet transaction's counterparty
name
string
The name of the counterparty

Min length: 1
numbers
object
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullable 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
string
The account number of the account. Maximum of 10 characters.

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

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

Min length: 15
Max length: 34
status
string
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
string
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3  "type": "PAYOUT",
4  "reference": "Payout 99744",
5  "amount": {
6    "iso_currency_code": "GBP",
7    "value": 123.12
8  },
9  "status": "EXECUTED",
10  "created_at": "2020-12-02T21:14:54Z",
11  "counterparty": {
12    "numbers": {
13      "bacs": {
14        "account": "31926819",
15        "sort_code": "601613"
16      }
17    },
18    "name": "John Smith"
19  },
20  "request_id": "4zlKapIkTm8p5KM"
21}

/wallet/transactions/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/transactions/list

Request fields and example

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

Min length: 1
cursor
string
A base64 value representing the latest transaction that has already been requested. Set this to next_cursor received from the previous /wallet/transactions/list request. If provided, the response will only contain transactions created before that transaction. 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
integer
The number of transactions to fetch

Minimum: 1
Maximum: 200
Default: 10 
1const request: WalletTransactionsListRequest = {
2  wallet_id: walletID,
3  count: 10,
4};
5try {
6  const response = await plaidClient.walletTransactionsList(request);
7  const transactions = response.data.transactions;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}
wallet/transactions/list

Response fields and example

transactions
[object]
An array of transactions of an e-wallet, associated with the given wallet_id
transaction_id
string
A unique ID identifying the transaction
reference
string
A reference for the transaction
type
string
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 initated payment made through Plaid's PIS APIs.

Possible values: BANK_TRANSFER, PAYOUT, PIS_PAY_IN, REFUND
amount
object
The amount and currency of a transaction
iso_currency_code
string
An ISO-4217 currency code, used with e-wallets and transactions.

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

Format: double
Minimum: 1
counterparty
object
An object representing the e-wallet transaction's counterparty
name
string
The name of the counterparty

Min length: 1
numbers
object
The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
nullable 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
string
The account number of the account. Maximum of 10 characters.

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

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

Min length: 15
Max length: 34
status
string
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
string
Timestamp when the transaction was created, in ISO 8601 format.

Format: date-time
next_cursor
string
Cursor used for fetching transactions created before the latest transaction provided in this response
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "next_cursor": "YWJjMTIzIT8kKiYoKSctPUB",
3  "transactions": [
4    {
5      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
6      "type": "PAYOUT",
7      "reference": "Payout 99744",
8      "amount": {
9        "iso_currency_code": "GBP",
10        "value": 123.12
11      },
12      "status": "EXECUTED",
13      "created_at": "2020-12-02T21:14:54Z",
14      "counterparty": {
15        "numbers": {
16          "bacs": {
17            "account": "31926819",
18            "sort_code": "601613"
19          }
20        },
21        "name": "John Smith"
22      }
23    },
24    {
25      "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
26      "type": "PAYOUT",
27      "reference": "Payout 99744",
28      "amount": {
29        "iso_currency_code": "EUR",
30        "value": 456.78
31      },
32      "status": "EXECUTED",
33      "created_at": "2020-12-02T21:14:54Z",
34      "counterparty": {
35        "numbers": {
36          "international": {
37            "iban": "GB33BUKB20201555555555"
38          }
39        },
40        "name": "John Smith"
41      }
42    }
43  ],
44  "request_id": "4zlKapIkTm8p5KM"
45}

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.

webhook_type
string
WALLET
webhook_code
string
WALLET_TRANSACTION_STATUS_UPDATE
transaction_id
string
The transaction_id for the wallet transaction being updated
new_status
string
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
string
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
string
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
environment
string
The Plaid environment the webhook was sent from

Possible values: development, 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  "new_status": "SETTLED",
6  "old_status": "INITIATED",
7  "timestamp": "2017-09-14T14:42:19.350Z",
8  "environment": "production"
9}