1. Partner Flow
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 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
    • 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
      POST
    • Get KYB/KYC submit + open account status
      GET
    • List Banks
      GET
    • Check Account
      POST
    • Add Account
      POST
    • Get Stablecoin Quote
      POST
    • Create Stable Order
      POST
    • Get Order (Single) Detail
      GET
    • List Orders(Batch)
      GET
    • Submit hash
      POST
    • 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. Partner Flow

Order Status Notification (STABLE_ORDER_UPDATED)

Developing
Webhook
POST
notifyTransactionStatus

Order Status Notification (Partner Flow · STABLE_ORDER_UPDATED)#

BPN sends an HTTP POST with a JSON body to your order webhook URL (configured for your merchant account) when an order created by POST /v1/stable/order/submit-order changes status. Webhook name: notifyTransactionStatus; eventType is always STABLE_ORDER_UPDATED.

When it is sent#

webhook statusquery-detail orderStatussent when
initINITOrder created by submit-order. Only sent if the initial notification is enabled for your merchant account (ask BPN to enable it).
successSUCCESSFiat paid out to targetAccountId.
failFAILOrder failed. Read failCode / failReason with query-detail.
refundedREFUNDEDRefund completed: the stablecoin was returned to userRefundCryptoAddress (e.g. the receiving bank / mobile money operator returned the payout after success).
status is lowercase in the webhook; query-detail returns uppercase orderStatus. Compare case-insensitively.
No webhook is sent for PROCESSING or REFUNDING.
A refunded webhook can arrive after a success webhook for the same referenceId: if the receiving bank / mobile money operator returns the payout, the order moves SUCCESS → REFUNDING → REFUNDED. Reverse the payout in your ledger when you receive refunded.
The webhook carries no amounts, fees or fail reasons. On every webhook, call GET /v1/stable/order/query-detail?orderId={referenceId} and treat that response as the source of truth before updating your ledger.

Body#

fieldtypenotes
eventIdstring (UUID)Unique per event. Retries of the same event reuse the same eventId.
eventTypestringSTABLE_ORDER_UPDATED
referenceIdstringBPN orderId returned by submit-order (not your merchantOrderId).
statusstringinit / success / fail / refunded (lowercase)
timestampinteger (int64)Event time, Unix epoch milliseconds.

Headers & signature#

When an API key is configured for your webhook, each request carries:
headernotes
API-KEYyour API key
API-TIMESTAMPtime the request was signed, Unix epoch milliseconds (regenerated on every retry)
API-SIGNATURElowercase hex HMAC-SHA256(rawBody + "&" + API-TIMESTAMP) keyed with your API secret
Verify the signature against the raw request body exactly as received (do not re-serialize the JSON) and reject requests whose signature does not match. We recommend also rejecting requests whose API-TIMESTAMP is more than 5 minutes off your server time.

Response & retries#

Return any HTTP 2xx to acknowledge. The response body is ignored.
A non-2xx response or a network error is retried with the same body and eventId: by default up to 5 times, after 1 min, 5 min, 15 min, 30 min and 60 min, and only within 24 hours of the first attempt.
Process idempotently: deduplicate by eventId. Events can arrive late or out of order, so always confirm the current status with query-detail.

Request

Header Params

Body Params application/jsonRequired

Examples
{
    "eventId": "6f1d2c3b-4a59-4e8f-9b0a-1c2d3e4f5a61",
    "eventType": "STABLE_ORDER_UPDATED",
    "referenceId": "ST2026102014120391827364519201",
    "status": "init",
    "timestamp": 1792476000123
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://your-api-server.com' \
--header 'API-KEY: pk_live_3f9a1c7e5b2d4a6c' \
--header 'API-TIMESTAMP: 1792476185501' \
--header 'API-SIGNATURE: 5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592' \
--header 'Content-Type: application/json' \
--data '{
    "eventId": "6f1d2c3b-4a59-4e8f-9b0a-1c2d3e4f5a61",
    "eventType": "STABLE_ORDER_UPDATED",
    "referenceId": "ST2026102014120391827364519201",
    "status": "init",
    "timestamp": 1792476000123
}'

Responses

🟢200OK
application/json
Return any HTTP 2xx to acknowledge. Non-2xx or network errors are retried.
Bodyapplication/json

Example
{}
Previous
Submit hash
Next
Enums quick reference
Built with