Deposit Whitelist Notification

One webhook covering the whole deposit-whitelist lifecycle. Branch on eventType — the envelope and
data shape are identical across the three values; only two data fields are conditional.

Deposited crypto is gated on the payer 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.

These events fire only for a deposit that actually goes through the whitelist flow. A deposit from a
source address that is already ACTIVE skips the flow and emits none of them — see below.

Guide: Wallet · Deposit whitelist

`eventType` routing

`eventType`	When	`data.whiteListStatus`	`data.creditStatus`	Order `status`	What you do
`DEPOSIT_WHITELIST_REQUIRED`	Deposit confirmed on chain and the source address is not yet whitelisted	`init`	`PENDING`	`PROCESSING`	`POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit`
`DEPOSIT_WHITELIST_FAILED`	Submitted payer details were rejected in review	`rejected`	`PENDING`	`PROCESSING`	Read `data.failMessage`, fix it, submit again for the same transaction
`DEPOSIT_WHITELIST_CREDITED`	Review passed for this deposit; funds moved into the available balance of the receiving wallet	`approved`	`CREDITED`	usually `PROCESSING`, can be `SUCCESS`	Book the funds. Not a terminal event

Conditional `data` fields

Everything else in data is always present.

Field	Present when
`failMessage`	`eventType` is `DEPOSIT_WHITELIST_FAILED`
`creditTime`	`eventType` is `DEPOSIT_WHITELIST_CREDITED`

Four things that are easy to get wrong

An already whitelisted address produces no event on this page at all. These three events describe the
whitelist flow, and a deposit from a source address that is already ACTIVE does not enter it. You get
neither DEPOSIT_WHITELIST_REQUIRED nor DEPOSIT_WHITELIST_CREDITED — only the ordinary
DEPOSIT_ORDER_NOTIFICATION when the deposit completes. Do not make booking a repeat deposit conditional on
receiving anything here.

DEPOSIT_WHITELIST_FAILED is not a failed deposit. The review was rejected, nothing is refunded and
nothing is lost. The order stays PROCESSING, creditStatus stays PENDING, the funds stay in the
unavailable balance. Resubmission is the expected next step.

DEPOSIT_WHITELIST_CREDITED does not mean the deposit finished. It means the money became spendable in
the receiving wallet. The order is usually still PROCESSING — auto-collection to the main account may
follow. Completion is signalled separately by DEPOSIT_ORDER_NOTIFICATION with status SUCCESS.

Read creditStatus, not the order status, to decide whether funds are usable. status PROCESSING
with creditStatus CREDITED is normal and means the funds are available.

Delivery

Configured exactly like the other Stable webhooks. Deduplicate on eventId — the same event may arrive
more than once, and DEPOSIT_WHITELIST_FAILED can legitimately arrive several times for one transaction
across resubmissions.

No DEPOSIT_ORDER_NOTIFICATION is emitted during on-chain confirmation; it arrives when the deposit is
fully complete and now carries whiteListStatus as well.

Not receiving any of these? Poll GET /v1/wallet/history?whiteListStatus=init (or rejected) for the work
queue, and GET /v1/wallet/transactions/{transactionId} for one transaction. The removed
GET /v1/wallet/deposit-whitelist/pending-list is no longer available.

Respond 200 promptly and process asynchronously.

Request

Authorization

API Key

Add parameter in header

API-KEY

Example:

API-KEY: ********************

API Key

Add parameter in header

API-SIGNATURE

Example:

API-SIGNATURE: ********************

API Key

Add parameter in header

API-TIMESTAMP

Example:

API-TIMESTAMP: ********************

Body Params application/json

Example

{
    "eventId": "evt_9f2c7b1e4a6d",
    "eventType": "DEPOSIT_WHITELIST_REQUIRED",
    "referenceId": "20573580428712136704",
    "status": "PROCESSING",
    "timestamp": 1757062800000,
    "data": {
        "transactionId": "20573580428712136704",
        "txHash": "0x9c1a4d2f6b8e0a7c3d5f1b9e2a4c6d8f0b2e4a6c8d0f2b4e6a8c0d2f4b6e8a01",
        "currency": "USDC",
        "network": "BSC",
        "fromAddress": "0x3a1F8C4e2b6C8c9D7fE2B8b5a1d3C9A0bE12F345",
        "memo": "",
        "amount": "100.00",
        "walletId": "123",
        "walletName": "Merchant Sub Wallet A",
        "status": "PROCESSING",
        "creditStatus": "PENDING",
        "whiteListStatus": "init",
        "failMessage": "Company address does not match the incorporation country",
        "creditTime": "2026-09-04T09:41:00Z"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Deposit Whitelist Notification