1. Virtual Account
BPN OpenAPI
  • Get started
    • Introduction to BPN
    • Introduction to API
    • Architecture Overview
    • Authentication
    • Environments
    • Response envelope
    • Idempotency
  • Guides
    • Virtual Account
      • Virtual Account Overview
      • VA · Payin
      • VA · Statuses
      • VA · Payout
      • VA · RFI
      • VA · Currencies & limits
      • VA Opening
        • VND VA Opening
        • BRL VA Opening
    • Wallet
      • Wallet · Transfer
      • Wallet · Assets & limits
      • Wallet · Deposit whitelist
      • Wallet · PaymentLink
      • Wallet Overview
      • Wallet · Deposit
      • Wallet · Statuses
      • Wallet · Withdraw
    • Convert
      • Convert Overview
      • Convert · Quote & submit
      • Convert · Business types
      • Convert · Pairs & limits
      • Convert · Statuses
  • API Reference
    • Virtual Account
      • Virtual Account field notes
      • Inquiry Master VA Balance
      • List Primary Virtual Accounts
      • Create Virtual Account
      • Get Virtual Account Detail
      • List Virtual Account
      • List Virtual Account Orders
      • Get Virtual Account Order Detail
      • Refund Virtual Account Order
      • List RFI Sub Virtual Account
      • Get Sub Virtual Account RFI Template Info
      • Sub Virtual Account Submit RFI
      • Add Bank Account
      • List Bank Account
      • List Banks
      • Payout via Virtual Account
      • Send Email Verify Code
    • Wallet
      • Wallet field notes
      • Deposit Whitelist
        • Get Deposit Whitelist Options
        • Register Deposit Source Address
        • List Deposit Source Addresses
        • Get Deposit Source Address
        • Disable Deposit Source Address
        • Submit Payer Details for a Received Deposit
        • Save Sub-wallet Payer Profile
        • Update Sub-wallet Payer Profile
        • Get Sub-wallet Payer Profile
        • Get Deposit Whitelist Case
      • Get Asset Balance
      • Get Deposit Address
      • Add Deposit Sender
      • Add Withdraw Whitelist
      • Delete Withdraw Whiltelist
      • Request Withdraw
      • Query Wallet Internal Transfer Detail
      • List Wallet Internal Transfer order
      • Wallet Internal Transfer
      • Create Sub Account
      • Query Transaction History
      • List Wallets
      • List Sub Account
      • Get Transaction Detail
      • List Wallet Transactions
      • Get Wallet Transaction Detail
    • Payment Link
      • Abnormal fund
        • Abnormal funds
        • Matchable Payment links
        • Link Order(Abnormal fund)
        • Submit to platform
      • Create Payment Link
      • List Payment links
      • Get Curreny Network Config
    • Convert
      • Convert field notes
      • Inquery FX Rate
      • Get Stablecoin Quote
      • Create Stable Order
      • Get Order (Single) Detail
      • List Orders(Batch)
    • KYB
      • Share KYB/KYC Info For Sub User
      • Get KYB Sub User Status
    • Reconciliation
      • Get Reconciliation Order List By Page
    • External Provider
      • FE: Create stablecoin collection sub-account link
      • FE: Deposit Travel Rule
      • External Provider · Deposit whitelist
      • Create stablecoin collection sub-account link
      • Get sub wallet account
      • List sub wallet accounts
      • Change sub wallet status
      • Query stablecoin collection order list
      • Query stablecoin collection order status
      • Get quote
      • Accept stablecoin collection order
      • Reject stablecoin collection order
      • Query USD balance
      • USD Payout (withdrawal)
      • Query USD Payout order status
      • Query USD Payout order list
      • Create deposit Travel Rule link
      • Create deposit Travel Rule detail link
    • Mock
      • Mock Virtual account Payin Order
      • Mock wallet deposit transaction
      • Mock Payin Order Refund
      • Mock Payout Order Update Status
    • Pay Session
      • Request Pay Session
    • Files
      • Request File Upload URL
  • Webhooks
    • Webhooks Overview
    • KYB notifications
    • Event catalogue
    • Resend Fail Webhook
    • Open Virtual Account Status
    • Virtual Account Payment Status
    • Virtual Account Invoice update
    • Transaction Status Notification
    • KYB Status Notification
    • Deposit Sender Detail Required
    • Abnormal Fund Notification
    • WALLET_TRANSFER_ORDER_UPDATED
    • Sub Virtual Account RFI Required
    • Sub Wallet Update
    • wallet address whitelist Update
    • Crypto Deposit Order Notification
    • Collect Order Updated
    • Usd Payout Order Updated
    • onboard result
    • partner order status
    • PaymentLink Notification
    • Deposit Whitelist Notification
  • Partner Flow
    • Share KYB/KYC and open account directly
    • Get KYB/KYC submit + open account status
    • Get Stablecoin Quote
    • Create Stable Order
    • Get Order (Single) Detail
    • List Orders(Batch)
    • Submit hash
  • Appendix
    • Enums quick reference
    • Enum
    • Virtual Account(VA) Support List & KYB requirement
  • Release Notes & Changelog
  • Errors
    • Error codes catalogue
  • Change Log
    • 2026-09-21 Virtual Account independent refund orders
    • Wallet deposit source-address whitelist
  1. Virtual Account

Virtual Account Overview

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#

CapabilityMeaningDeep dive
PayinPayer sends funds to a sub VA → fiat creditedVA · Payin
PayoutFiat out from VA to a bank accountVA · Payout
RFICompliance remediation branchVA · RFI
Ancillary (not mainline): bank account bookkeeping /v1/account/* (API Reference · More).

Pages in this product#

PageContent
OverviewThis page
PayinPayin sequence & reconciliation keys
PayoutPayout & refunds
RFIRemediation
StatusesAccount / order state machines
Currencies & limitsCurrency & limit ownership
VND VA OpeningVA Opening · VND beneficiary profile & rules
BRL VA OpeningVA Opening · BRL beneficiary profile & rules
Field-level: API Reference · Virtual Account

Core API index#

ScenarioMethodPath
Master balanceGET/v1/virtual-account/primary/get-balance
Master listGET/v1/virtual-account/primary/list
Create sub VAPOST/v1/virtual-account/sub/create
Request file upload URLPOST/v1/files/upload-url
Get / list sub VAGET/sub/get · /sub/list
Email verify codePOST/v1/virtual-account/email/send-verify-code
Query bank infoPOST/v1/virtual-account/query-bank-account-info
Order detail / listGET/order/detail · /order/list
PayoutPOST/v1/virtual-account/order/payout
RefundPOST/v1/virtual-account/order/refund
RFIGET/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. Currencies whose opening takes no documents — BRL among them — do not call it.

Webhooks (this product)#

eventTypeScenario
VIRTUAL_ACCOUNT_UPDATEDAccount status
VIRTUAL_ACCOUNT_ORDER_UPDATEDPayin / Payout order
SUB_VIRTUAL_ACCOUNT_RFI_REQUIREDRFI 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#

1.
Confirm fiat results only on terminal states (VA · Statuses).
2.
Drive remediation via webhooks — do not blindly re-fire payout while RFI is pending.
3.
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
1.
Provision or retrieve the receiving details supported by the selected market.
2.
Present the bank account, payment key, QR code, or payment link to the payer.
3.
Receive a webhook when the incoming payment is confirmed.
4.
Use the returned orderId to query and reconcile the same PayIn order.
5.
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.

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).
CurrencyReview requiredProfileIntegration guide
BRLYesName, tax identification number, country. No documentsBRL VA Opening
VNDYesIndividual: identity profile. Company: company profile, supporting documents, and the people behind the companyVND VA Opening
MXN · NGN · KES · GHSNoProvisioned directly—
The four account statuses are the same for every currency: INIT → PROCESSING (account under review) → SUCCESS or FAIL. 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.
Previous
Idempotency
Next
VA · Payin
Built with