Inquiry Master VA Balance

Prerequisite

Before calling this endpoint, contact BPN to provision a Master Virtual Account for your partner profile. BPN will allocate the master account and share the allocated account ID with you — this ID is returned in the response as primaryAccountId and is referenced consistently across wallet and payout APIs as virtualAccountId. The query will not return meaningful results until provisioning is complete.

Query the available balance of the Master Virtual Account (Master VA) for a given fiat currency (ISO 4217). Returns usable balance, internal primary account id (primaryAccountId, same as wallet virtualAccountId), and balanceString for display.

Query parameters

currency (required): ISO 4217 code (e.g. BRL, USD, EUR).

externalAccountId (optional): forwarded to the wallet service when applicable.

Use cases

Pre-check balance before payout or transfer.

Treasury monitoring by currency.

Request

Authorization

API Key

Add parameter in header

X-BPN-API-KEY

Example:

X-BPN-API-KEY: ********************

API Key

Add parameter in header

X-BPN-SIGNATURE

Example:

X-BPN-SIGNATURE: ********************

API Key

Add parameter in header

X-BPN-TIMESTAMP

Example:

X-BPN-TIMESTAMP: ********************

Query Params

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Success or business error envelope; check status and code.

Bodyapplication/json

Examples

Success (BRL)Success (USD)Business error (example)

{
    "status": 200,
    "msg": "OK",
    "code": null,
    "data": {
        "primaryAccountId": "1000123456",
        "currency": "BRL",
        "balance": 1999.5,
        "balanceString": "1999.5"
    },
    "traceId": "39d760f9a1814c4896a774bcf79da528"
}