BPN
  1. Account Management
BPN
  • Getting Started
    • Introduction to BPN
    • Key Concepts & Terminology
    • Architecture Overview
  • Onboarding & Prerequisites
    • Product Demo
    • Sandbox & Test Environment
  • Use Case
    • Transfer
    • Vault
    • On/Off Ramp
    • Compliance (Travel Rule Information Submission)
  • API Reference
    • KYB
      • Share KYB Info For Sub User
      • Get KYB Sub User Status
    • Account Management
      • add bank account
        POST
      • list bank account
        GET
      • create virtaul account
        POST
      • list virtual account
        GET
      • Master VA balance inquiry
        GET
      • list virtual account orders
        GET
      • refund virtual account order
        POST
    • Wallet
      • Get Asset Balance
      • Get Deposit Address
      • Add Deposit Sender
      • Add Withdraw Whitelist
      • Delete Withdraw Whiltelist
      • Request Withdraw
      • Query Transaction History
    • FX
      • fx inquery
    • BPN Transactions
      • get stablecoin quote
      • create stable order
      • get order (single) detail
      • list orders(batch)
    • Reconciliation
  • Webhooks & Event
    • resend fail webhook
      POST
    • KYB Status Notification
      POST
    • Transaction Status Notification
      POST
    • Account Status Notification
      POST
    • Open Virtual Account Status
      POST
    • Deposit Sender Detail Required
      POST
    • virtual account payment status
      POST
  • Appendix
    • Enum
    • Virtual Account(VA) Support List
  • Release Notes & Changelog
    • Version History
  • Schemas
    • Schemas
      • walletBalance
      • walletAddress
      • transactionRecord
  1. Account Management

add bank account

POST
/v1/account/add-account
Use this endpoint to maintain a fiat account that will be used as either a payer (debit/outgoing) account or a beneficiary (credit/incoming) account.
Important: this API is for fiat rails only (e.g., PIX, local bank, SEPA, SWIFT). It is not for crypto addresses or on-chain wallets.

What it’s for#

Transfer flow
• Add your payer account so we can validate ownership and accept funds from you.
• Add your beneficiary account so we can off-ramp and deliver the converted fiat to the right destination.
Sell flow
• Add your beneficiary account to receive the fiat proceeds after the sale.
Please note: The beneficiary account for these two flows can be the same, meaning you only need to maintain one account to use it in multiple places.

Scope & variability#

We support multiple payment networks and corridors (e.g., PIX/BR, SEPA/EU, SWIFT/global, and other local rails). The required fields change dynamically by networkType and country:
• Example:
BRL(PIX)
USD(SWIFT)
EUR(SEPA)
CNPJ or CPF: A unique identifier for users or merchants in Brazil.
PIX Key: Used for receiving and making payments, supporting information such as email, phone number, or CNPJ.
Account Holder Name: Client KYB/KYC name.

Validation & compliance#

1.
BPN verifies:
2.
Ownership / name match (payer side) to reduce third-party risk.
3.
Format & network consistency (e.g., IBAN structure, bank code validity, currency–country alignment).
4.
Eligibility of the rail for incoming/outgoing payments on the specified corridor.
5.
Depending on corridor, we may require additional data to support Travel Rule / payer information capture and internal compliance checks.

Rules & best practices#

1.
You can store multiple payer and beneficiary accounts per merchant.
2.
Use accountType to indicate whether you are adding a PAYER or BENEFICIARY account.
3.
Use networkType (e.g., PIX, SEPA, SWIFT, LOCAL) and country / currency to select the rail; the API will enforce the correct field set for accountInfo.
4.
Add accounts before you request a transfer/sell; downstream transactions reference accountId only.
5.
For payer accounts, ensure the legal name and document ID match your onboarding/KYB/KYC records; mismatches may be rejected.

Typical flow#

1
First Step
Merchant calls Add Account to register payer/beneficiary details for a given rail.
2
Second Step
BPN validates the data and returns a unique accountId with status.
3
Third Step
Merchant reuses accountId when calling Transfer Estimation / Confirm Transfer (payer & beneficiary) or Sell (beneficiary).

Request

Body Params application/json

Examples

Responses

🟢200OK
application/json
Body

Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST '/v1/account/add-account' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accountType": "PAYER",
    "networkType": "PIX",
    "country": "BR",
    "currency": "BRL",
    "accountInfo": {
        "cpfOrCnpj": "12345678900",
        "pixKey": "test@email.com",
        "accountHolderName": "João Silva"
    }
}'
Response Response Example
{
    "status": 0,
    "message": "string",
    "data": {
        "accountId": "string",
        "bindStatus": "string"
    },
    "traceId": "string"
}
Modified at 2025-09-10 14:00:42
Previous
Get KYB Sub User Status
Next
list bank account
Built with