1. Wallet
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. Wallet

Wallet Overview

Wallet (Stablecoin) Overview#

Product: Wallet · Stablecoin
Capabilities: deposit / withdraw / Payment Link collection (+ optional internal transfer)
API prefix: /v1/wallet/*
Updated: 2026-08-09 · Phase C · English
Commons: Get started · Webhooks · Errors
Related: Virtual Account · Convert

What it does#

CapabilityMeaningDeep dive
DepositOn-chain credit to merchant/sub walletWallet · Deposit
Payment LinkStablecoin collection via payment link (funds land in collect wallet)Wallet · Deposit · section B
WithdrawOn-chain send to external addressWallet · Withdraw
TransferWallet-to-wallet transfer (optional)Wallet · Transfer
Deposit whitelistRegister the payer source address and payer details. Required before deposited funds become availableWallet · Deposit whitelist

Pages#

PageContent
OverviewThis page
DepositOn-chain deposit & Payment Link collection
WithdrawWithdraw & whitelist
TransferInternal transfer
StatusesStatuses & actions
Assets & limitsAssets, networks & limits
Deposit whitelistSource-address whitelisting, payer details & crediting
Field-level: API Reference · Wallet

Payment Link collection flow#

Payment Link is a Wallet inbound path alongside on-chain deposit. Typical lifecycle:
Create payment link
        ↓
Deliver link to payer
        ↓
Payer completes payment
        ↓
PAYMENT_LINK_UPDATED webhook
        ↓
Funds in collect wallet → (optional) Transfer → operation wallet → Convert
Steps:
1.
POST /v1/stable/collect/create-payment-link
2.
Hand the payment link to the payer
3.
Receive PAYMENT_LINK_UPDATED; query via POST /v1/stable/collect/payment-links if needed
4.
If funds cannot be matched: UNALLOCATED_FUND_RECEIVED → abnormal-fund APIs
5.
(Optional) After funds enter the collect wallet, Transfer to the operation wallet, then Convert
Full diagrams (on-chain + Payment Link + overview flowchart): Wallet · Deposit.
Payment Link APIs live under API Reference · Payment Link.

Core API index#

ScenarioMethodPath
List walletsGET/v1/wallet/list
Create sub walletPOST/v1/wallet/create/sub
Sub account listGET/v1/wallet/sub-account/list
Asset balanceGET/v1/wallet/asset-balance
Deposit addressGET/v1/wallet/deposit-address
Add deposit senderPOST/v1/wallet/add-deposit-sender
Deposit whitelist — providersGET/v1/wallet/deposit-whitelist/options
Deposit whitelist — source addressesPOST · GET/v1/wallet/deposit-whitelist/addresses
Deposit whitelist — submit for a depositPOST/v1/wallet/deposit-whitelist/transactions/{transactionId}/submit
Deposit whitelist — sub-wallet payer profilePOST · PUT · GET/v1/wallet/deposit-whitelist/wallets/{walletId}/profile
Transaction detailGET/v1/wallet/transaction/detail
Create payment linkPOST/v1/stable/collect/create-payment-link
WithdrawPOST/v1/wallet/withdraw
Whitelist add/deletePOSTadd-withdraw-whitelist / delete-withdraw-whitelist
Internal transferPOST/v1/wallet/transfer
Transfer queriesGETtransfer-order/detail · /list
HistoryGET/v1/wallet/transaction/list — supports the whiteListStatus filter

Webhooks#

eventTypeScenario
DEPOSIT_ORDER_NOTIFICATIONDeposit progress and completion — carries whiteListStatus. PROCESSING with init / rejected is the whitelist gate; SUCCESS is completion
DEPOSIT_SENDER_DETAIL_UPDATEDDeposit sender required
WALLET_ADDRESS_UPDATEDAddress update
PAYMENT_LINK_UPDATEDPayment Link collection
UNALLOCATED_FUND_RECEIVEDUnmatched Payment Link funds
WALLET_WITHDRAW_UPDATEDWithdraw
WALLET_TRANSFER_ORDER_UPDATEDInternal transfer
SUB_WALLET_UPDATEDSub-wallet (incl. v2 scenarios)

Integration baseline#

1.
Deposit depends on chain confirmation — REST will not return final success at broadcast time.
2.
Payment Link credits the collect wallet first; transfer to the operation wallet before Convert when needed.
3.
Withdraw requestId is a fund-safety baseline — reuse the same key on timeout.
4.
Amounts are decimal strings; network must match the address family — see Wallet · Assets & limits.
5.
Deposited funds are gated on the payer source address. Until the whitelist review passes they stay in the unavailable balance of the receiving wallet. Read creditStatus, not the order status, to decide whether money is spendable — see Wallet · Deposit whitelist.
6.
whiteListStatus replaces submitStatus and is lowercase: init · pending · approved · rejected. It appears on GET /v1/wallet/transaction/list, GET /v1/wallet/transaction/detail, GET /v2/stable/collect/order-status, DEPOSIT_ORDER_NOTIFICATION and Collect Order Updated. GET /v1/wallet/deposit-whitelist/pending-list and .../cases/{transactionId} were removed.
Previous
Wallet · PaymentLink
Next
Wallet · Deposit
Built with