1. Change Log
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
      • 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
      POST
    • 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. Change Log

Wallet deposit source-address whitelist

Overview#

Effective date not yet confirmed. This page documents an API set that is still in design
(BPNPBLIC-220, parent BPNPBLIC-143 / Jira BPN-1595). Do not treat the contract as live, and do
not code-generate production clients from it until backend implementation is confirmed.
Deposited crypto is gated on the payer's source address. Until the address is whitelisted and the
payer details pass review, the deposit order is PROCESSING and the funds sit in the unavailable
balance of the receiving wallet — not withdrawable, not convertible. After approval the funds move
to the available balance of that same wallet; auto-collection, where enabled, then sweeps them to
the main account and only afterwards does the order turn SUCCESS.
Guide: Wallet · Deposit whitelist

Revision — 2026-09-07#

The contract was reworked after the first draft. If you already read this page, these are the
breaking differences.
ChangeDetail
submitStatus → whiteListStatusValues are now lowercase init / pending / approved / rejected, replacing PENDING / SUBMITTED / REJECTED / DONE
Pending list removedGET /v1/wallet/deposit-whitelist/pending-list is gone. Use GET /v1/wallet/transaction/list with the whiteListStatus filter
Case endpoint removedGET /v1/wallet/deposit-whitelist/cases/{transactionId} is gone. Use GET /v1/wallet/transaction/detail
/options narrowedReturns providers only. The country enum was dropped
Country as ISO codeSend countryCode as an ISO 3166-1 alpha-2 code (SG). countryInfo was withdrawn — the platform derives the country name server-side
Whitelisted address skips the flowA deposit from a source address that is already ACTIVE does not enter the whitelist flow and never shows a gate — whiteListStatus comes through as approved or null
Sub-wallet payer profile restoredPOST / PUT / GET /v1/wallet/deposit-whitelist/wallets/{walletId}/profile are back in scope. Use them when a sub-wallet always receives from one payer who may send from several addresses
Transaction queries consolidatedGET /v1/wallet/history is deprecated in favour of GET /v1/wallet/transaction/list. The draft GET /v1/wallet/transactions/{transactionId} was withdrawn in favour of GET /v1/wallet/transaction/detail. Every reference in these docs now points at the surviving pair
whiteListStatus on existing surfacesAdded to GET /v1/wallet/transaction/list, GET /v2/stable/collect/order-status, DEPOSIT_ORDER_NOTIFICATION and Collect Order Updated
No standalone whitelist eventsThe gate is carried on the order webhook you already consume instead of on a dedicated event
Integration impact. A handler that waits for a dedicated whitelist event will never fire. Read
whiteListStatus off DEPOSIT_ORDER_NOTIFICATION or Collect Order Updated, or poll
GET /v1/wallet/transaction/detail.

New endpoints#

Under API Reference · Wallet, status designing.
MethodPath
GET/v1/wallet/deposit-whitelist/options
POST/v1/wallet/deposit-whitelist/addresses
GET/v1/wallet/deposit-whitelist/addresses
GET/v1/wallet/deposit-whitelist/addresses/{id}
POST/v1/wallet/deposit-whitelist/addresses/{id}/disable
POST/v1/wallet/deposit-whitelist/transactions/{transactionId}/submit
POST/v1/wallet/deposit-whitelist/wallets/{walletId}/profile
PUT/v1/wallet/deposit-whitelist/wallets/{walletId}/profile
GET/v1/wallet/deposit-whitelist/wallets/{walletId}/profile

Changed existing endpoints#

EndpointChange
GET /v1/wallet/transaction/listNew optional whiteListStatus query filter; records carry whiteListStatus and creditStatus. Absorbs the description of the deprecated GET /v1/wallet/history
GET /v1/wallet/transaction/detailwhiteListStatus and creditStatus added to data, directly after status
GET /v2/stable/collect/order-statusdata.whiteListStatus added, directly after data.orderStatus
Webhook DEPOSIT_ORDER_NOTIFICATIONdata.whiteListStatus added, normally approved
Webhook Collect Order Updateddata.whiteListStatus added
All four changes are additive — no field was removed or retyped.

Contract notes#

Amounts are decimal strings; currency / symbol stay separate fields.
Write operations accept an Idempotency-Key request header — the first merchant APIs on the
platform to do so. See Idempotency.
A registered source address is not editable. Correcting it means disable plus register again.
When submitting for a deposit that already arrived, never send walletAddress, network, memo,
symbol or txHash; they come from the on-chain transaction (10000106).
Business failures return status 500 with an 8-digit WalletErrorCode in code
(10000100–10000107). 10000103 now also covers an invalid countryCode or an unknown
provider. See Errors catalogue.

Status contract#

status does not indicate spendability. Read creditStatus from
GET /v1/wallet/transaction/detail, or the
available balance from GET /v1/wallet/asset-balance.
statuswhiteListStatuscreditStatusMeaning
PROCESSINGinitPENDINGPayer details not submitted
PROCESSINGpendingPENDINGUnder review, funds unavailable
PROCESSINGrejectedPENDINGRejected — resubmit, funds unavailable
PROCESSINGapprovedCREDITEDNormal — funds available, deposit not finished (auto-collection running)
SUCCESSapprovedCREDITEDDeposit fully complete
anyanyBLOCKEDNot credited — contact support

Webhook events#

No dedicated whitelist event is emitted. The gate is read off the order webhook you already consume,
as data.whiteListStatus.
eventTypeGate — payer details neededTerminal
DEPOSIT_ORDER_NOTIFICATIONstatus PROCESSING with whiteListStatus init or rejectedstatus SUCCESS, normally whiteListStatus approved
COLLECT_ORDER_UPDATEDorderStatus PROCESSING with whiteListStatus init or rejectedorderStatus SUCCESS
WALLET_ADDRESS_UPDATED—Source-address review moved to ACTIVE or FAILED
Answer a gate with POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit. Whitelist
approval is not announced on its own — completion is the order webhook reaching SUCCESS. See
Event catalogue.

Removed#

ItemReplacement
GET /v1/wallet/deposit-whitelist/pending-listGET /v1/wallet/transaction/list with whiteListStatus
GET /v1/wallet/deposit-whitelist/cases/{transactionId}GET /v1/wallet/transaction/detail
GET /v1/wallet/history (deprecated, still served)GET /v1/wallet/transaction/list
GET /v1/wallet/transactions/{transactionId} (draft, withdrawn)GET /v1/wallet/transaction/detail
submitStatuswhiteListStatus
Country enum in /optionscountryCode as ISO 3166-1 alpha-2
countryInfo in requestsDerived server-side from countryCode

Unchanged#

Withdrawal whitelisting still uses POST /v1/wallet/add-withdraw-whitelist. The existing
POST /v1/wallet/add-deposit-sender flow and its DEPOSIT_SENDER_DETAIL_UPDATED event were not
modified by this release.
Previous
2026-09-21 Virtual Account independent refund orders
Built with