Managing your Virtual Account 
==============================

#### Set up, control, and monitor virtual account activity 

Virtual Accounts are not enabled by default in Sandbox. To get access in Sandbox or Production, [contact sales](https://plaid.com/contact) or your account manager. Once enabled, start by calling [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) .

#### Accessing Virtual Account details 

To fetch virtual account details, use [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) or [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) .

#### Fund your Virtual Account 

You can top up your virtual account in two ways: a manual bank transfer or [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) . In Sandbox, virtual accounts must be funded using Payment Initiation.

To fund a virtual account via a manual bank transfer, initiate a transfer from your bank account by specifying the virtual account numbers as the transaction's recipient.

To fund a virtual account via Payment Initiation, follow the typical [Payment Initiation flow](https://plaid.com/docs/payment-initiation/payment-initiation-one-time/index.html.md) . Use the `recipient_id` associated with your `wallet_id` so Plaid knows to route the payment to your virtual account.

#### Webhooks 

An [overview of webhooks at Plaid](https://plaid.com/docs/api/webhooks/index.html.md) is available in the API Reference. There you can find general information on Plaid webhooks, including IP addresses, webhook verification, and retry logic.

To get status updates on all transaction activity in the virtual account, set up a webhook listener endpoint via the [Plaid Dashboard](https://dashboard.plaid.com/developers/webhooks) . Use the `Wallet transaction event` type with your webhook URL. Plaid will fire the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook to alert you when there are any changes to the status of a transaction.

#### Reconciling transactions 

To reconcile transactions:

1.  Call the [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) or [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoint for the virtual account you want to pull transactions for.
    
2.  Cross-check the received transaction IDs with your stored transactions and compare the transaction statuses to ensure they are up to date. If the stored status is different, update it with the transaction status from the [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) or [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoint in Step 1.
    

Plaid supports the [transaction types linked here](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet-transaction-get-response-type) .

Valid [transaction statuses](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet-transaction-get-response-status) for each transaction type are outlined below.

##### Credit transactions 

Credit transaction types: `PIS_PAY_IN` and `BANK_TRANSFER`

| Status      | Terminal   | Valid transitions   | Description |
| --- | --- | --- | --- |
| INITIATED | No | SETTLED, FAILED | The transaction has been initiated. |
| SETTLED | Yes |  | The transaction has settled in the virtual account. |
| FAILED | Yes |  | The transaction could not be executed, for example, due to an invalid recipient or invalid reference. |

##### Debit transactions 

Debit transaction types: `PAYOUT` and `REFUND`

| Status      | Terminal   | Valid transitions   | Description |
| --- | --- | --- | --- |
| AUTHORISING | No | INITIATED, FAILED, BLOCKED | The transaction is being processed for validation and compliance. |
| INITIATED | No | EXECUTED, FAILED | The transaction passed authorisation checks and is being processed by the payment network. |
| EXECUTED | Yes |  | The transaction has been successfully executed. Plaid does not have visibility into the settlement of debit transactions in the destination account. A transaction will typically settle within seconds to several days, depending on which payment rail is used. On rare occasions, a transaction may fail to settle after being executed, for example, if it is rejected by the payment rails due to compliance or anti-money-laundering checks. |
| FAILED | Yes |  | The transaction failed, for example, due to an invalid recipient or invalid reference. |
| BLOCKED | Yes |  | The transaction was blocked due to compliance checks and could not be executed. |

#### Idempotency 

An idempotency key is a unique value generated by you that allows Plaid to identify subsequent retries of the same request. A unique idempotency key should be generated for each different request. An idempotency key should be re-used only when retrying an existing request. You can choose how to create unique keys. We suggest using either V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 128 characters long.

Idempotency keys are valid for 24 hours after the first request. After 24 hours, any request reusing a previously-used idempotency key will be treated as a new request. When two requests with the same idempotency key, within 24 hours, have a different payload, the request will result in an error.

The `idempotency_key` is required for the [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) and [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) endpoints as it allows users to safely retry failed requests without creating a duplicate transaction. By providing the same `idempotency_key` for the same request, no more than one transaction is created.