External Provider · Deposit whitelist

Audience: external provider integration teams.
Scope: the Wallet OpenAPI and webhooks that apply once deposit source-address whitelisting is switched on.

Authentication, the response envelope and idempotency are the same as every other Stable Wallet endpoint.
Send an Idempotency-Key header on writes. All amounts are strings.

Field-level reference: Wallet · Deposit whitelist.

1. What this is

A payer sends crypto to a merchant receiving wallet. If the source address has not been whitelisted yet,
the money lands in the unavailable balance of that receiving wallet — not withdrawable, not convertible.
You submit the payer details through the OpenAPI; once the whitelist review passes, the funds credit into the
receiving wallet and the order continues to SUCCESS.

There is no provider-specific endpoint. You call the same /v1/wallet/deposit-whitelist/** and wallet
query endpoints as every other merchant.

There are two ways to get an address whitelisted. They can coexist, and once a source address is ACTIVE
neither one asks for the payer details again.

	When to use it	Entry point
Path A — register the address up front	You know the payer's source address before they send	`POST /v1/wallet/deposit-whitelist/addresses`
Path B — submit after the deposit lands	You learn the address only from the incoming transaction	`POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit`

Both do Travel Rule whitelisting on the payer source address. The only difference is whether you do it
before or after the money arrives.

2. The one rule that matters

orderStatus = SUCCESS is not what tells you the money is spendable, and it is not what tells you the
whitelist cleared.

Read three independent fields:

Field	Question it answers
`orderStatus` / order `status`	Has the whole order finished?
`whiteListStatus`	Has the Travel Rule review cleared?
`creditStatus`	Is the money in the receiving wallet's available balance?

The common mid-flight combination is orderStatus = PROCESSING + whiteListStatus = approved +
creditStatus = CREDITED: whitelisting is done and the funds are credited, while the order is still being
processed (for example a sweep to the main account). That is normal, not an error.

3. The two paths

3.1 Path A — register the address up front

GET /v1/wallet/deposit-whitelist/options — fetch the VASP provider list.

POST /v1/wallet/deposit-whitelist/addresses — submit the address plus the Travel Rule details.
Cannot be edited after submission.

Poll GET /v1/wallet/deposit-whitelist/addresses/{id}, or wait for WALLET_ADDRESS_UPDATED, until the
address is ACTIVE. If it comes back FAILED, disable it and register a new one.

The payer sends to the address from GET /v1/wallet/deposit-address.

Because the source address is already ACTIVE, the deposit skips the whitelist flow entirely and
credits as an ordinary deposit.

No DEPOSIT_WHITELIST_* webhook fires on this path. Neither DEPOSIT_WHITELIST_REQUIRED nor
DEPOSIT_WHITELIST_CREDITED. Do not make booking conditional on receiving one — the order webhook is your
only signal.

3.2 Path B — submit after the deposit lands

The payer sends first, from an address that has not been whitelisted.

On-chain confirmation puts the order in PROCESSING and the funds in the unavailable balance.

You receive DEPOSIT_WHITELIST_REQUIRED (whiteListStatus = init).

Optionally GET /v1/wallet/deposit-whitelist/options. Use
GET /v1/wallet/history?whiteListStatus=init or GET /v1/wallet/transactions/{transactionId} to read the
transaction and its read-only source address.

POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit with the Travel Rule details only.

Review runs (pending). If it is rejected you get DEPOSIT_WHITELIST_FAILED and submit again; if it
passes you get DEPOSIT_WHITELIST_CREDITED.

The order finishes with COLLECT_ORDER_UPDATED at orderStatus = SUCCESS.

The address is now ACTIVE, so later deposits from it behave like Path A.

3.3 Resubmitting after a rejection

Path	What to do
A	The address is `FAILED`. Call `POST /v1/wallet/deposit-whitelist/addresses/{id}/disable`, then register a new address with corrected details. An address key cannot be edited in place.
B	Call `POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit` again. The on-chain address fields still must not be sent.

Find the affected items with GET /v1/wallet/history?whiteListStatus=rejected.

Do not use POST /v1/wallet/add-withdraw-whitelist for this — that is the withdrawal whitelist, a
different feature.

4. Status fields

Full table: Wallet · Statuses.

4.1 Order `status` / `orderStatus`

Value	Meaning
`PROCESSING`	In flight — awaiting details, under review, or credited but not yet finished
`SUCCESS`	The whole order is complete
`FAIL`	Failed
`REJECTED`	Rejected; a refund state may follow
`REFUNDING`	Refund in progress
`REFUNDED`	Refunded

4.2 `whiteListStatus`

Value	Meaning	What you do
`init`	Travel Rule details not submitted	Path B: call submit. Path A: get the address to `ACTIVE`
`pending`	Submitted, under review	Wait
`approved`	Cleared	Wait for the order to reach `SUCCESS`
`rejected`	Rejected	Resubmit — see 3.3

It is null for transactions and orders that are not gated by the whitelist.

4.3 `creditStatus`

Value	Meaning
`PENDING`	Not yet in the receiving wallet's available balance
`CREDITED`	In the receiving wallet. A sweep may still follow
`BLOCKED`	Could not be credited — contact support

4.4 Source address `status` (Path A only)

Value	Meaning
`PROCESSING`	Submitted, under review
`ACTIVE`	Approved. Later deposits from it skip the whitelist flow
`FAILED`	Rejected. Disable it and register again

5. Webhooks

Deduplicate on eventId. Full catalogue: Event catalogue.

5.1 Deposit Whitelist Notification

The three whitelist events are delivered by a single webhook, distinguished by eventType. The envelope
and data shape are identical across all three.

`eventType`	Meaning	Order status	What you do
`DEPOSIT_WHITELIST_REQUIRED`	This deposit needs payer details; funds are in the unavailable balance	`PROCESSING`, `whiteListStatus = init`	Call submit with the Travel Rule details. Do not change the payer address, network or memo
`DEPOSIT_WHITELIST_FAILED`	Details were rejected; funds still unavailable	`PROCESSING`, `whiteListStatus = rejected`	Read `data.failMessage`, correct it, submit again
`DEPOSIT_WHITELIST_CREDITED`	Review passed; funds are now in the receiving wallet's available balance	usually still `PROCESSING`, `whiteListStatus = approved`, `creditStatus = CREDITED`	Update the balance you show. Not the end of the order

These three fire only for a deposit that actually goes through the whitelist flow. A deposit from a
source address that is already ACTIVE emits none of them.

5.2 `WALLET_ADDRESS_UPDATED`

A source address in the address book changed state — mainly useful on Path A. Read the address status:
ACTIVE means you can keep collecting from it, FAILED means disable and re-register.

5.3 `COLLECT_ORDER_UPDATED`

Order progress and completion for collection / payment-link orders. Branch on orderStatus (see 4.1);
data.whiteListStatus is carried alongside it.

Order completion is signalled only by COLLECT_ORDER_UPDATED with orderStatus = SUCCESS. Whitelist
progress never arrives through this event, and the whitelist events never mean the order is finished.

For plain wallet deposits that are not behind a collection order, the equivalent completion event is
DEPOSIT_ORDER_NOTIFICATION, which also carries whiteListStatus.

5.4 Typical sequences

Address not whitelisted yet (Path B)

DEPOSIT_WHITELIST_REQUIRED → you submit

optionally DEPOSIT_WHITELIST_FAILED → you submit again

DEPOSIT_WHITELIST_CREDITED → funds credited to the receiving wallet

one or more COLLECT_ORDER_UPDATED → final one at orderStatus = SUCCESS

Address already whitelisted (Path A, and every repeat deposit)

no whitelist event at all

one or more COLLECT_ORDER_UPDATED → final one at orderStatus = SUCCESS

6. Endpoint inventory

6.1 Deposit whitelist

Method	Path	Path A / B	Purpose
`GET`	`/v1/wallet/deposit-whitelist/options`	A / B	VASP provider list. Countries use ISO two-letter codes
`POST`	`/v1/wallet/deposit-whitelist/addresses`	A	Register an address with Travel Rule details
`GET`	`/v1/wallet/deposit-whitelist/addresses`	A	Paginated address book
`GET`	`/v1/wallet/deposit-whitelist/addresses/{id}`	A	One address and its deposits
`POST`	`/v1/wallet/deposit-whitelist/addresses/{id}/disable`	A	Disable, then register again
`POST`	`/v1/wallet/deposit-whitelist/transactions/{transactionId}/submit`	B	Submit Travel Rule details for a received deposit

6.2 Deposit and wallet queries

Method	Path	Purpose
`POST`	`/v1/wallet/create/sub`	Create a receiving sub-wallet
`GET`	`/v1/wallet/deposit-address`	Deposit address
`GET`	`/v1/wallet/asset-balance`	Available / unavailable balance
`GET`	`/v1/wallet/history`	Supports `whiteListStatus=init\|pending\|approved\|rejected` as a filter
`GET`	`/v1/wallet/transactions/{transactionId}`	One transaction: `status`, `whiteListStatus`, `creditStatus`
`GET`	`/v1/wallet/list`, `/v1/wallet/sub-account/list`	Wallet lists

6.3 Transfer and withdrawal (after the deposit clears)

Method	Path	Note
`POST`	`/v1/wallet/transfer`	Available balance only
`GET`	`/v1/wallet/transfer-order/detail`, `/v1/wallet/transfer-order/list`	Transfer queries
`POST`	`/v1/wallet/withdraw`	Withdrawal
`POST`	`/v1/wallet/add-withdraw-whitelist`	Withdrawal whitelist — not deposit source whitelisting
`POST`	`/v1/wallet/delete-withdraw-whitelist`	Remove a withdrawal whitelist entry

6.4 Collection

The existing Stable collect / payment-link query endpoints and webhooks are unchanged, except that
whiteListStatus now sits next to orderStatus in the order payload.

6.5 Do not use

Item	Why
`POST /v1/wallet/add-deposit-sender`	Not wired up for this flow. Use `/v1/wallet/deposit-whitelist/**`
`/v1/wallet/deposit-whitelist/pending-list`	Removed. Use `GET /v1/wallet/history` with `whiteListStatus`
`/v1/wallet/deposit-whitelist/cases/{transactionId}`	Removed. Use `GET /v1/wallet/transactions/{transactionId}`

7. Examples

7.1 Provider options

GET /v1/wallet/deposit-whitelist/options

{
  "providers": [
    { "name": "Binance" },
    { "name": "Coinbase" }
  ]
}

7.2 Path A — register an address

POST /v1/wallet/deposit-whitelist/addresses, header Idempotency-Key

{
  "requestId": "uuid",
  "walletLabel": "Payport Limited",
  "network": "BSC",
  "walletAddress": "0x…",
  "memo": "",
  "symbol": "USDC",
  "addressType": "STANDARD",
  "walletType": "VASP",
  "provider": "Binance",
  "correspondentType": "ENTITY",
  "fullName": "Payport Limited",
  "countryCode": "SG",
  "companyAddress": "Tampines Blk67, Singapore"
}

countryCode is ISO 3166-1 alpha-2, for example SG. Do not send countryInfo.

ENTITY requires fullName, countryCode, companyAddress.

INDIVIDUAL requires firstName, lastName, birthday (yyyy-MM-dd), countryCode,
residentialAddress, and no fullName.

Response data:

{
  "id": "10001",
  "status": "PROCESSING"
}

7.3 Path B — submit for a received deposit

POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit, header Idempotency-Key

{
  "requestId": "uuid",
  "correspondentType": "ENTITY",
  "fullName": "Payport Limited",
  "countryCode": "SG",
  "companyAddress": "Tampines Blk67, Singapore",
  "walletLabel": "Payport Limited",
  "addressType": "STANDARD",
  "walletType": "VASP",
  "provider": "Binance"
}

Never send walletAddress, network, memo, symbol or txHash. The on-chain transaction is the source
of truth, and this endpoint whitelists exactly the address that sent it.

Response data:

{
  "status": "PROCESSING",
  "whiteListStatus": "pending",
  "transactionIds": ["20573580428712136704"]
}

7.4 Transaction detail

GET /v1/wallet/transactions/{transactionId} → data

{
  "transactionId": "20573580428712136704",
  "status": "PROCESSING",
  "whiteListStatus": "init",
  "creditStatus": "PENDING",
  "failMessage": "",
  "fromAddress": "0x…",
  "network": "BSC",
  "amount": "100.00",
  "currency": "USDC"
}

8. Error codes

Business status is 200 on success. On failure it is 500 and code carries one of these. Full list:
Error codes catalogue.

`code`	Meaning
`10000100`	Transaction does not exist, or does not belong to this account
`10000101`	Payer details for this deposit have already been reviewed
`10000102`	Payer details incomplete
`10000103`	Invalid field value, including an unknown `countryCode` or `provider`
`10000104`	Cannot submit right now. Poll the status — do not edit the details and retry immediately
`10000105`	Duplicate request
`10000106`	The payer address cannot be supplied or changed when submitting for a received deposit

9. Integration checklist

Path A and Path B are handled separately, each against the sequence in §3

Subscribed to the Deposit Whitelist Notification webhook and to COLLECT_ORDER_UPDATED; on Path A also
to WALLET_ADDRESS_UPDATED

Booking a deposit is not conditional on a DEPOSIT_WHITELIST_* event — an already whitelisted
address emits none

A whitelist rejection (DEPOSIT_WHITELIST_FAILED) and an order rejection (COLLECT_ORDER_UPDATED with
orderStatus = REJECTED) are handled as different things

DEPOSIT_WHITELIST_CREDITED updates the balance but does not close the order; completion is
COLLECT_ORDER_UPDATED at orderStatus = SUCCESS

Path B submit never carries on-chain address fields; countries are two-letter codes only

Pending work is found with GET /v1/wallet/history?whiteListStatus=init|rejected

The withdrawal whitelist endpoints are not used for deposit source whitelisting

Every write carries an Idempotency-Key — see Idempotency

External Provider · Deposit whitelist

1. What this is#

2. The one rule that matters#

3. The two paths#

3.1 Path A — register the address up front#

3.2 Path B — submit after the deposit lands#

3.3 Resubmitting after a rejection#

4. Status fields#

4.1 Order status / orderStatus#

4.2 whiteListStatus#

4.3 creditStatus#

4.4 Source address status (Path A only)#

5. Webhooks#

5.1 Deposit Whitelist Notification#

5.2 WALLET_ADDRESS_UPDATED#

5.3 COLLECT_ORDER_UPDATED#

5.4 Typical sequences#

6. Endpoint inventory#

6.1 Deposit whitelist#

6.2 Deposit and wallet queries#

6.3 Transfer and withdrawal (after the deposit clears)#

6.4 Collection#

6.5 Do not use#

7. Examples#

7.1 Provider options#

7.2 Path A — register an address#

7.3 Path B — submit for a received deposit#

7.4 Transaction detail#

8. Error codes#

9. Integration checklist#