Plaid logo
Docs
ALL DOCS

Payment Initiation (UK and Europe)

  • Introduction to Payment Initiation
  • Add Payment Initiation to your app
  • User onboarding and account funding
  • Add Variable Recurring Payments to your app
  • Virtual Accounts
    • Managing your Virtual Account
    • Payment Confirmation
    • Payouts
    • Refunds
    • Account Sweeping
    • Add Virtual Accounts to your app
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
  • Which countries does Investments support?
  • What is Remember Me?
  • How do I enable IDV selfie checks?
Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
Plaid.com
Log in
Get API Keys
Open nav

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:

  1. Call the /wallet/transaction/get or /wallet/transaction/list 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 or /wallet/transaction/list endpoint 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
INITIATEDNoSETTLED, FAILEDThe transaction has been initiated.
SETTLEDYesThe transaction has settled in the virtual account.
FAILEDYesThe 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
AUTHORISINGNoINITIATED, FAILED, BLOCKEDThe transaction is being processed for validation and compliance.
INITIATEDNoEXECUTED, FAILEDThe transaction passed authorisation checks and is being processed by the payment network.
EXECUTEDYesThe 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.
FAILEDYesThe transaction failed, for example, due to an invalid recipient or invalid reference.
BLOCKEDYesThe 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.

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