Virtual Account (Fiat) Overview

Product: Virtual Account · Fiat
Capabilities: payin, payout
API prefix: /v1/virtual-account/*
Updated: 2026-08-27 · 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
VND VA Opening	VA Opening · VND beneficiary profile & rules
BRL VA Opening	VA Opening · channel selection and Woovi profile
GOWD BRL Corporate VA Opening	GOWD corporate profile, uploads and result tracking

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`
Request file upload URL	POST	`/v1/files/upload-url`
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`

/v1/files/upload-url is a general-purpose endpoint, not a Virtual Account one. It issues a short-lived pre-signed URL so file bytes are uploaded straight to object storage and then referenced by fileId. VA opening is one caller: a VND company application references its supporting documents this way. GOWD BRL corporate applications also upload three supporting document categories through this endpoint. Channels whose opening takes no documents, such as the Woovi flow, do not call it. See GOWD BRL Corporate VA Opening.

Webhooks (this product)

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

Status highlights

Dynamic account extra statuses: EXPIRED (VA expired), REJECTED (payment rejected, funds returned to source). Refunds use a separate RE* child (PAYIN_REFUND / PAYOUT_REFUND); the original VA* order stays SUCCESS. Details: VA · Statuses.

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

Capabilities below depend on the channel and merchant entitlement. GOWD supports Corporate STATIC opening; a QR code is not guaranteed. See GOWD BRL Corporate VA Opening.

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.

2b. VA opening by currency

Some markets require the beneficiary profile to pass review before the receiving instrument is issued. For these currencies, Create Virtual Account also carries the beneficiary profile, and a 200 means the application was accepted — not that the account exists. Track the outcome on Open Virtual Account Status and confirm it with Get VA Detail (GET /v1/virtual-account/sub/get).

Currency	Review required	Profile	Integration guide
BRL · Woovi	Yes	Name, tax identification number, country; no documents	BRL VA Opening
BRL · GOWD	Yes	Corporate STATIC; CNPJ, legal name, UBO, PEP declaration, three uploaded document categories	GOWD BRL Corporate VA Opening
VND	Yes	Individual: identity profile. Company: company profile, supporting documents, and the people behind the company	VND VA Opening
MXN · NGN · KES · GHS	No	Provisioned directly	—

Account status families are shared, but the initial status depends on the channel. GOWD normally starts at PROCESSING, then reaches SUCCESS or FAIL; do not require an INIT response first. See VA · Statuses.

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 orderStatus=SUCCESS on the original VA* order.

Refund terminal events are notified on the RE* child (PAYIN_REFUND / PAYOUT_REFUND).

Use orderId as the unique identifier for tracking the order being notified.

Process webhook events idempotently.

Use the order query API as a fallback when verification is required. Do not infer refund success from timeout.

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

5. Refund a PayIn or Payout

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

BPN creates a separate RE* child (businessType PAYIN_REFUND or PAYOUT_REFUND).

The original VA* order orderStatus stays SUCCESS. Use refundStatus / refundOrderId on the original, and originalOrderId on the child.

Track the child: orderStatus=PROCESSING + refundStatus=REFUNDING → REFUNDED+REFUNDED or FAIL+REFUND_FAILED.

Webhook terminal refund events are on the RE* child, not original-order orderStatus=REFUNDED.

Timeout or missing callback must not be treated as success.

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)#

Status highlights#

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)#

2b. VA opening by currency#

3. Provision receiving details#

4. Receive and track payments#

5. Refund a PayIn or Payout#

6. Query orders and balances#

Operational order query#

Master VA balance#

7. Reports and reconciliation#

8. Integration requirements#