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
        • GOWD BRL Corporate 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
        GET
      • List Primary Virtual Accounts
        GET
      • Create Virtual Account
        POST
      • Get Virtual Account Detail
        GET
      • List Virtual Account
        GET
      • List Virtual Account Orders
        GET
      • Get Virtual Account Order Detail
        GET
      • Refund Virtual Account Order
        POST
      • List RFI Sub Virtual Account
        GET
      • Get Sub Virtual Account RFI Template Info
        GET
      • Sub Virtual Account Submit RFI
        POST
      • Add Bank Account
        POST
      • List Bank Account
        GET
      • List Banks
        GET
      • Payout via Virtual Account
        POST
      • Send Email Verify Code
        POST
    • 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
      • Prepay Whitelist for One-Time Payment Link
      • Prepay Whitelist for Permanent Payment Link
    • 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 Payment Link deposit
      • 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
    • List Banks
    • Check Account
    • Add Account
    • Get Stablecoin Quote
    • Create Stable Order
    • Get Order (Single) Detail
    • List Orders(Batch)
    • Submit hash
    • Order Status Notification (STABLE_ORDER_UPDATED)
  • 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

Create Virtual Account

POST
/v1/virtual-account/sub/create
Purpose:
Opens a sub virtual account. For most currencies the account is provisioned directly. For currencies that require the beneficiary profile to pass review first — currently VND and BRL — the same endpoint also carries the beneficiary profile, and the account is created only after the application passes review.
VA opening guides:
CurrencyGuide
VNDVND VA Opening
BRLBRL VA Opening
Each guide carries the full field tables and validation rules for that currency. The sections below cover only what is common to both.
How to use:
1.
(VND corporate and GOWD BRL corporate) For every supporting document, call Request File Upload URL (POST /v1/files/upload-url), PUT the bytes to the returned uploadUrl, and keep the fileId. File requirements depend on the channel; GOWD requires three supporting document categories.
2.
POST /v1/virtual-account/sub/create with currency, accountSubType=STATIC, userType, and the profile required by the selected channel. GOWD uses top-level cnpj and kycFormData; other channels may use individualInfo or companyInfo. The fields inside those objects differ per currency; follow the guide for the currency you are opening.
3.
Store the returned virtualAccountId.
4.
Track the outcome on Open Virtual Account Status, and confirm it with Get VA Detail (GET /v1/virtual-account/sub/get) until status becomes SUCCESS or FAIL.
Notes:
A 200 means the application was accepted, not that the account exists. No account number, PIX key or QR code is returned at submit time.
The initial status depends on the channel and processing progress: INIT or PROCESSING. GOWD defaults to PROCESSING. Treat the account as usable only at SUCCESS; read failReason at FAIL.
Review is measured in business days, not seconds. Keep a scheduled query as a fallback in case a webhook is delayed or missed — do not block a user-facing request on the outcome, and do not instruct anyone to remit funds before SUCCESS.
Structured profile objects use camelCase according to their channel guide. Questionnaire kycFormData keys are exact question IDs: GOWD uses snake_case, which must not be renamed.
For channels using structured profile objects, userType selects the applicable profile. GOWD corporate onboarding uses cnpj and kycFormData; neither nested profile object is required.
Re-submitting an application for an account that already reached SUCCESS is rejected; correct and re-submit only after a FAIL.

GOWD BRL corporate onboarding#

See GOWD BRL Corporate VA Opening for the complete upload → create → query flow. Select an GOWD BRL primaryAccountId confirmed by BPN. Only Corporate (CorporateSlave compatibility) + STATIC is accepted.
Required: CNPJ; legal name; UBO name/type; cartao_cnpj, contrato_social and ubo_id_document fileIds; actual PEP declaration and its conditional fields. Files must be uploaded using VA_ONBOARDING + BRL before submission. Do not send fileListMap, inline base64, storage keys/URLs or legacy document objects. companyInfo.businessType/industry are not needed.
The shared schema lists channel-specific fields; requiredness for GOWD is described here because the channel is resolved from the primary account/default routing. Existing non-GOWD BRL and VND examples remain channel-specific.

GOWD validation errors#

Missing required data may produce MISSING_REQUIRED_INFO, unsupported user type INVALID_USER_TYPE, and invalid file/input INVALID_PARAMETER before environment error-code mapping. Parser failures use HTTP 400; other failures may use a business error envelope. An INVALID_PARAMETER file metadata query failure can also indicate a dependency problem. Preserve traceId for support.

Request

Authorization
API Key
Add parameter in header
API-KEY
Example:
API-KEY: ********************
API Key
Add parameter in header
API-SIGNATURE
Example:
API-SIGNATURE: ********************
API Key
Add parameter in header
API-TIMESTAMP
Example:
API-TIMESTAMP: ********************
or
Body Params application/json

Examples
Here is an example for MXN VA creation
{
  "primaryAccountId": "",
  "currency": "MXN",
  "companyName": "Test Company",
  "accountSubType": "STATIC",
  "externalAccountId": "EX-CORP-249973-001",
  "userType": "Corporate",
  "companyInfo": {
    "entityName": "Test Company",
    "incorporatedCountry": "MX",
    "incorporatedDate": "2024-05-24",
    "registrationNumber": "ABC210315K12",
    "companyAddress": "XXXX 217, XXXXXX, 64763, XXX City, Monterrey",
    "phoneNumber": "+5212345678",
    "email": "ashleigh19@hotmail.com",
    "businessType": "B2B",
    "industry": "Private Education & Training Services"
  }
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/v1/virtual-account/sub/create' \
--header 'API-KEY: <api-key>' \
--header 'API-SIGNATURE: <api-key>' \
--header 'API-TIMESTAMP: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "primaryAccountId": "",
  "currency": "MXN",
  "companyName": "Test Company",
  "accountSubType": "STATIC",
  "externalAccountId": "EX-CORP-249973-001",
  "userType": "Corporate",
  "companyInfo": {
    "entityName": "Test Company",
    "incorporatedCountry": "MX",
    "incorporatedDate": "2024-05-24",
    "registrationNumber": "ABC210315K12",
    "companyAddress": "XXXX 217, XXXXXX, 64763, XXX City, Monterrey",
    "phoneNumber": "+5212345678",
    "email": "ashleigh19@hotmail.com",
    "businessType": "B2B",
    "industry": "Private Education & Training Services"
  }
}'

Responses

🟢200OK
application/json
Bodyapplication/json

Example
{
    "status": "PROCESSING",
    "message": "OK",
    "data": {
        "virtualAccountId": "va_10001",
        "accountName": "ACME LTD",
        "currency": "USDT",
        "status": "SUCCESS",
        "qrCode": "sample_qrCode",
        "qrCodeImage": "sample_qrCodeImage",
        "subAccountType": "sample_subAccountType",
        "expireTime": 1690000030000,
        "amount": "50.00",
        "pixKeyType": "sample_pixKeyType",
        "pixKey": "sample_pixKey",
        "bankName": "sample_bankName",
        "bankCode": "sample_bankCode",
        "externalAccountId": "ext_acc_001",
        "failReason": "string",
        "accountNumber": "string",
        "bankBranchCode": "string",
        "bankIspb": "string",
        "channelAccountId": "string",
        "iban": "string"
    },
    "traceId": "a1b2c3d4e5f6",
    "success": true
}
Previous
List Primary Virtual Accounts
Next
Get Virtual Account Detail
Built with