Plaid logo
Docs
ALL DOCS

Virtual Accounts (UK and Europe)

  • Introduction to Virtual Accounts
  • Managing your Virtual Account
  • Payment Confirmation
  • Payouts
  • Refunds
  • Account Sweeping
  • Add Virtual Accounts to your app
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Add Virtual Accounts to your app

Use virtual accounts to gain additional insight and control over the flow of funds

In this guide, we'll walk through how to set up and manage virtual accounts. After integrating you will be able to send and receive money, make withdrawals and refunds, and reconcile funds for faster reconciliation.

Note: The Sandbox environment uses test data and does not interact with financial institutions.

Integrate with Plaid Payment Initiation and enable Virtual Accounts

Virtual accounts are designed to be used in conjunction with the Payment Initiation APIs. To get the most out of Plaid virtual accounts, first add Payment Initiation to your app. In order to be enabled for Virtual Accounts in Production, contact your Account Manager. To test in Sandbox, begin by creating a virtual account via /wallet/create.

Select Language
Copy
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}

Enable Virtual Account Transaction webhooks

Enable virtual account webhooks to receive notifications when new transaction events occur. Plaid will send a webhook for each transaction event. These notifications can be used to stay updated on transaction status information.

Funding your Virtual Account through Payment Initiation

Create a Payment that will be initiated to your virtual account
Select Language
Copy
1const request: PaymentInitiationPaymentCreateRequest = {
2 recipient_id: recipientID,
3 reference: 'TestPayment',
4 amount: {
5 currency: 'GBP',
6 value: 100.0,
7 },
8};
9try {
10 const response = await plaidClient.paymentInitiationPaymentCreate(request);
11 const paymentID = response.data.payment_id;
12 const status = response.data.status;
13} catch (error) {
14 // handle error
15}

Use the recipient_id associated with your wallet_id so Plaid knows to route the payment to your virtual account.

Launch and complete the Payment Initiation flow in Link

For more details on how to do this, see the Payment Initiation documentation.

Confirm that the payment has settled via a payment webhook

For more details, see the PAYMENT_STATUS_UPDATE webhook.

Copy
1{
2 "webhook_type": "PAYMENT_INITIATION",
3 "webhook_code": "PAYMENT_STATUS_UPDATE",
4 "payment_id": "<PAYMENT_ID>",
5 "new_payment_status": "PAYMENT_STATUS_SETTLED",
6 "old_payment_status": "PAYMENT_STATUS_EXECUTED",
7 "original_reference": "Account Funding 99744",
8 "adjusted_reference": "Account Funding 99",
9 "original_start_date": "2017-09-14",
10 "adjusted_start_date": "2017-09-15",
11 "timestamp": "2017-09-14T14:42:19.350Z"
12}
Confirm that funds have arrived in your virtual account via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

Copy
1{
2 "webhook_type": "WALLET",
3 "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4 "wallet_id": "<WALLET_ID>",
5 "new_status": "SETTLED",
6 "old_status": "INITIATED",
7 "timestamp": "2021-09-14T14:42:19.350Z"
8}

Executing a Payout

Fetch your virtual account to confirm it has sufficient balance
Select Language
Copy
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}
Execute a payout
Select Language
Copy
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}
Confirm the payout was executed, via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

Copy
1{
2 "webhook_type": "WALLET",
3 "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4 "wallet_id": "<WALLET_ID>",
5 "new_status": "EXECUTED",
6 "old_status": "INITIATED",
7 "timestamp": "2021-09-14T14:42:19.350Z"
8}

Refunding a Payment Initiation payment

Fetch your virtual account to confirm it has sufficient balance
Select Language
Copy
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}
Refund a Payment Initiation payment
Select Language
Copy
1const request: PaymentInitiationPaymentReverseRequest = {
2 payment_id: paymentID,
3 reference: 'Refund for purchase ABC123',
4 idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
5};
6try {
7 const response = await plaidClient.paymentInitiationPaymentReverse(request);
8 const refundID = response.data.refund_id;
9 const status = response.data.status;
10} catch (error) {
11 // handle error
12}
Confirm the refund was executed, via a transaction webhook

For more details, see the WALLET_TRANSACTION_STATUS_UPDATE webhook.

Copy
1{
2 "webhook_type": "WALLET",
3 "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE",
4 "wallet_id": "<WALLET_ID>",
5 "new_status": "EXECUTED",
6 "old_status": "INITIATED",
7 "timestamp": "2021-09-14T14:42:19.350Z"
8}

Next steps

If you're ready to launch to Production, see the Launch checklist.

Launch checklist

Recommended steps to take before launching in Production

Launch
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord