Virtual Account (Fiat) Overview

Product: Virtual Account · Fiat
Capabilities: payin, payout
API prefix: /v1/virtual-account/*
Updated: 2026-08-09 · Phase C multi-page · English

Platform commons: Get started · Webhooks · Errors

Related: Wallet · Convert

What it does

Capability	Meaning	Deep dive
Payin	Payer sends funds to a sub VA → fiat credited	VA · Payin
Payout	Fiat out from VA to a bank account	VA · Payout
RFI	Compliance remediation branch	VA · RFI

Ancillary (not mainline): bank account bookkeeping /v1/account/* (API Reference · More).

Pages in this product

Page	Content
Overview	This page
Payin	Payin sequence & reconciliation keys
Payout	Payout & refunds
RFI	Remediation
Statuses	Account / order state machines
Currencies & limits	Currency & limit ownership

Field-level: API Reference · Virtual Account

Core API index

Scenario	Method	Path
Master balance	GET	`/v1/virtual-account/primary/get-balance`
Master list	GET	`/v1/virtual-account/primary/list`
Create sub VA	POST	`/v1/virtual-account/sub/create`
Get / list sub VA	GET	`/sub/get` · `/sub/list`
Email verify code	POST	`/v1/virtual-account/email/send-verify-code`
Query bank info	POST	`/v1/virtual-account/query-bank-account-info`
Order detail / list	GET	`/order/detail` · `/order/list`
Payout	POST	`/v1/virtual-account/order/payout`
Refund	POST	`/v1/virtual-account/order/refund`
RFI	GET/POST	`/sub/rfi-template` · `/sub/submit-rfi` · `/sub/rfi-list`

Webhooks (this product)

eventType	Scenario
`VIRTUAL_ACCOUNT_UPDATED`	Account status
`VIRTUAL_ACCOUNT_ORDER_UPDATED`	Payin / Payout order
`SUB_VIRTUAL_ACCOUNT_RFI_REQUIRED`	RFI required

Integration baseline

Confirm fiat results only on terminal states (VA · Statuses).

Drive remediation via webhooks — do not blindly re-fire payout while RFI is pending.

Do not mix orderId semantics across Convert / Wallet.

Fiat collection via Virtual Accounts & local collection rails

Use BPN's fiat collection APIs to receive local-currency payments through Virtual Accounts, local payment instructions, or pooled collection accounts.

The high-level integration lifecycle is standardized across markets, while the receiving instrument, required fields, limits, and operational rules vary by currency.

One integration model, market-specific capabilities

Integrate the common order, webhook, query, refund, and reconciliation model once. Before enabling a currency, review its supported collection instrument and market-specific requirements. Common fiat currencies for VA collection: BRL, MXN, NGN, KES, GHS — see VA · Currencies & limits.

1. Standard collection flow

Provision or retrieve receiving details
                ↓
Payer sends local-currency funds
                ↓
Receive PayIn webhook notification
                ↓
Query and reconcile the collection order
                ↓
Refund or use the available balance

Provision or retrieve the receiving details supported by the selected market.

Present the bank account, payment key, QR code, or payment link to the payer.

Receive a webhook when the incoming payment is confirmed.

Use the returned orderId to query and reconcile the same PayIn order.

Refund the payment when eligible, or use the available fiat balance in subsequent flows.

2. Supported markets

BRL

Static PIX Key

Static QR Code generated with the PIX Key

Dynamic QR Code

Maximum Dynamic QR validity: 72 hours

MXN

CLABE account

NGN

Collection account

KES

Collection account

GHS

Dedicated Virtual Account

One VA is assigned to each merchant or end user

Other markets (entitlement-dependent)

Additional rails (for example COP Dynamic Payment Link, ZAR Pool Account / dedicated named account) may be available per merchant entitlement. Confirm with Customer Success before enabling.

3. Provision receiving details

Use Create Virtual Account to provision a dedicated or dynamic receiving instrument where supported. For pooled collection markets, use the Pool Account receiving details available to the merchant.

Receiving instruments fall into three categories:

Persistent receiving details: Static PIX Key, CLABE, collection account, or Virtual Account.

Dynamic payment instructions: Dynamic QR Code or Dynamic Payment Link with a defined validity period.

Pooled collection: Shared Pool Account with an assigned reference code for transaction attribution.

All account provisioning requests are processed asynchronously. Subscribe to Open Virtual Account Status to receive the final account-opening result.

4. Receive and track payments

Subscribe to Virtual Account Payment Status to receive incoming payment notifications.

For PayIn orders:

A confirmed PayIn is notified as SUCCESS.

PayIn does not use PROCESSING.

Use orderId as the unique identifier for tracking the order.

Process webhook events idempotently.

Use the order query API as a fallback when verification is required.

For detailed webhook and refund status rules, see VA · Statuses and VA · Payin.

5. Refund a PayIn

Use Refund Virtual Account Order to request a refund for an eligible successful PayIn.

The refund is returned through the supported original-route process.

REFUNDING means the PayIn refund is being processed.

The final refund status is REFUNDED or REFUND_FAIL.

Keep the refund associated with the original PayIn order for lifecycle tracing and reconciliation.

System-initiated refunds may also occur when an incoming payment exceeds an applicable account or transaction limit.

6. Query orders and balances

Operational order query

Use List Virtual Account Orders to review and reconcile incoming payment orders.

Master VA balance

Use Master VA Balance Inquiry to query the merchant's fiat balance by currency.

Once the collected balance is available, it may be used in supported payout, transfer, or stablecoin conversion flows. All supported collection currencies can be converted to USDC or USDT — see Convert Overview.

7. Reports and reconciliation

Use Get Reconciliation Order List By Page for periodic billing and reconciliation of incoming payments.

Merchants should reconcile:

BPN orderId and merchant-side order records.

Payment amount and currency.

PayIn and refund statuses.

Balance movements.

Operational order results and period-end reports.

8. Integration requirements

Use a unique request identifier when creating resources or initiating transactions.

Use orderId as the primary identifier for PayIn tracking.

Verify webhook signatures before processing events.

Process repeated webhook events idempotently.

Use active order queries when a webhook is delayed or additional verification is required.

Do not assume that account type, required fields, limits, or refund support are identical across markets.

Virtual Account Overview

Virtual Account (Fiat) Overview#

What it does#

Pages in this product#

Core API index#

Webhooks (this product)#

Integration baseline#

Fiat collection via Virtual Accounts & local collection rails#

1. Standard collection flow#

2. Supported markets#

BRL#

MXN#

NGN#

KES#

GHS#

Other markets (entitlement-dependent)#

3. Provision receiving details#

4. Receive and track payments#

5. Refund a PayIn#

6. Query orders and balances#

Operational order query#

Master VA balance#

7. Reports and reconciliation#

8. Integration requirements#