Managing your Virtual Account
Set up, control, and monitor virtual account activity
By default, you are able to create virtual accounts in Sandbox. Start by calling /wallet/create. In order to use virtual accounts in Production, contact your Account Manager.
Accessing Virtual Account details
To fetch virtual account details, use /wallet/get or /wallet/list.
Fund your Virtual Account
You can top up your virtual account in two ways: a manual bank transfer or Payment Initiation. 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. 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 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. Use the Wallet transaction event type with your webhook URL. Plaid will fire the WALLET_TRANSACTION_STATUS_UPDATE webhook to alert you when there are any changes to the status of a transaction.
Reconciling transactions
To reconcile transactions:
Call the
/wallet/transaction/getor/wallet/transaction/listendpoint for the virtual account you want to pull transactions for.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/getor/wallet/transaction/listendpoint in Step 1.
Plaid supports the transaction types linked here.
Valid transaction statuses 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 transactions 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 and /payment_initiation/payment/reverse 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.