Virtual Accounts (UK and Europe)

API reference for Virtual Accounts endpoints and webhooks

Manage the entire lifecycle of a payment.

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
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
requiredstring
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
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
available
number
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
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
nullableobject
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
status
string
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
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    "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
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  const recipientID = response.data.recipient_id;
10} catch (error) {
11  // handle error
12}
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
available
number
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
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
nullableobject
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
status
string
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
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    "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
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: 1024
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
available
number
The total amount of funds in the account after subtracting pending debit transaction amounts

Format: double
numbers
object
An object representing the e-wallet account numbers
bacs
nullableobject
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
nullableobject
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
status
string
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
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        "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
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
The account number and sort code of the counterparty's account
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
address
object
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
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
requiredstring
The city where the recipient is located. Maximum of 35 characters.

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

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

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

Format: date
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: 0.01
reference
requiredstring
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 
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
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
wallet_id
string
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
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 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
nullablestring
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
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: 0.01
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
nullableobject
The account number and sort code of the counterparty's account
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
nullableobject
International Bank Account Number for a Wallet Transaction
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[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
string
The city where the recipient is located. Maximum of 35 characters.

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

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

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

Format: date
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
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestring
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
nullablestring
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
related_transactions
[object]
A list of wallet transactions that this transaction is associated with, if any.
id
string
The ID of the related transaction.
type
string
The type of the transaction.

Possible values: PAYOUT, RETURN, REFUND, FUNDS_SWEEP
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  "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
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/transaction/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
options
object
Additional wallet transaction options
start_time
string
Timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date.

Format: date-time
end_time
string
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]
An array of transactions of an e-wallet, associated with the given wallet_id
transaction_id
string
A unique ID identifying the transaction
wallet_id
string
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
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 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
nullablestring
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
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: 0.01
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
nullableobject
The account number and sort code of the counterparty's account
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
nullableobject
International Bank Account Number for a Wallet Transaction
iban
string
International Bank Account Number (IBAN).

Min length: 15
Max length: 34
address
nullableobject
The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
street
[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
string
The city where the recipient is located. Maximum of 35 characters.

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

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

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

Format: date
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
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
payment_id
nullablestring
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
nullablestring
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
related_transactions
[object]
A list of wallet transactions that this transaction is associated with, if any.
id
string
The ID of the related transaction.
type
string
The type of the transaction.

Possible values: PAYOUT, RETURN, REFUND, FUNDS_SWEEP
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      "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.

webhook_type
string
WALLET
webhook_code
string
WALLET_TRANSACTION_STATUS_UPDATE
transaction_id
string
The transaction_id for the wallet transaction being updated
payment_id
string
The payment_id associated with the transaction. This will be present in case of REFUND and PIS_PAY_IN.
wallet_id
string
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
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: 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}