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 · Currencies & limits
      • VA · Payout
      • VA · RFI
    • Wallet
      • Wallet · Withdraw
      • Wallet · Transfer
      • Wallet · Assets & limits
      • Wallet · Deposit whitelist
      • Wallet Overview
      • Wallet · Deposit
      • Wallet · Statuses
    • 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
      • 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
    • 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
      • 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
    • Mock
      • Mock Virtual account Payin Order
      • Mock wallet deposit transaction
      • Mock Payin Order Refund
      • Mock Payout Order Update Status
    • Pay Session
      • Request Pay Session
  • 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
    • inquiry supported currency
    • KYC/KYB Sharing
    • inquiry onboard status
    • get price
    • Create order
    • order list
    • inquiry single order
    • get user deposit address
    • get payment instruction
    • sync fund notification
    • daily settlement records
  • 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/history with the whiteListStatus filter
Case endpoint removedGET /v1/wallet/deposit-whitelist/cases/{transactionId} is gone. Use GET /v1/wallet/transactions/{transactionId}
/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 emits no DEPOSIT_WHITELIST_* webhook at all — neither REQUIRED nor CREDITED. Only DEPOSIT_ORDER_NOTIFICATION is sent
whiteListStatus on existing surfacesAdded to GET /v1/wallet/history, GET /v2/stable/collect/order-status, DEPOSIT_ORDER_NOTIFICATION and Collect Order Updated
Integration impact. A handler that waits for any DEPOSIT_WHITELIST_* event before booking a
deposit will stall on repeat deposits from a whitelisted address, because none of those events
fires. Reconcile on DEPOSIT_ORDER_NOTIFICATION, or poll
GET /v1/wallet/transactions/{transactionId}.

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
GET/v1/wallet/transactions/{transactionId}

Changed existing endpoints#

EndpointChange
GET /v1/wallet/historyNew optional whiteListStatus query filter; deposit records carry whiteListStatus
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–10000106). 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/transactions/{transactionId}, 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

New webhook events#

The three new events share one page under Webhooks — Deposit Whitelist Notification —
keyed on eventType, with the shared payload schema and one example body per event. This follows the
existing Transaction Status Notification entry, which likewise covers several eventType values.
eventTypewhiteListStatusOrder statusTerminal?
DEPOSIT_WHITELIST_REQUIREDinitPROCESSINGNo — submit payer details
DEPOSIT_WHITELIST_FAILEDrejectedPROCESSINGNo — resubmit, funds still unavailable
DEPOSIT_WHITELIST_CREDITEDapprovedusually PROCESSINGNo — funds available, deposit not finished
All three fire only for a deposit that goes through the whitelist flow. A deposit from an
already ACTIVE address emits none of them.
| DEPOSIT_ORDER_NOTIFICATION | normally approved | SUCCESS | Yes — existing production event, now with whiteListStatus |
DEPOSIT_ORDER_NOTIFICATION is not sent at the chain-confirmation stage. WALLET_ADDRESS_UPDATED
carries source-address review transitions. See Event catalogue.

Removed#

ItemReplacement
GET /v1/wallet/deposit-whitelist/pending-listGET /v1/wallet/history with whiteListStatus
GET /v1/wallet/deposit-whitelist/cases/{transactionId}GET /v1/wallet/transactions/{transactionId}
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