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 whitelist gate appears on this path. The order never comes back with whiteListStatus init or
rejected. Do not make booking conditional on a whitelist signal — 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.

COLLECT_ORDER_UPDATED arrives with orderStatus = PROCESSING and whiteListStatus = init.

Optionally GET /v1/wallet/deposit-whitelist/options. Use
GET /v1/wallet/transaction/list?whiteListStatus=init or GET /v1/wallet/transaction/detail 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 the next COLLECT_ORDER_UPDATED carries
whiteListStatus = rejected and you submit again; if it passes, whiteListStatus becomes approved.

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/transaction/list?whiteListStatus=rejected.

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

3.4 Whitelist first, then accept

A gated order is not acceptable while the whitelist gate is open. It becomes acceptable only after the
payer details clear review and the funds are credited. At that moment acceptStatus turns
ACCEPTING and a COLLECT_ORDER_UPDATED goes out — that is the signal to call
POST /v2/stable/collect/order/accept.

Stage	What you observe	What you do
Deposit received, compliance running	`orderStatus = PROCESSING`, `acceptStatus = INIT`	Nothing
Whitelist gate open	`whiteListStatus` `init` (first time) or `rejected` (sent back)	Submit or resubmit the Travel Rule details
Under review	`whiteListStatus = pending`	Wait
Cleared and credited	`whiteListStatus = approved`, `creditStatus = CREDITED`	Wait for `acceptStatus`
Acceptable	`acceptStatus = ACCEPTING`	Call accept with the current `quote.quoteId` — or reject to refund
Accepted	`acceptStatus = ACCEPTED`	Wait
Finished	`orderStatus = SUCCESS`	Settle

An early accept silently does nothing. If acceptStatus is anything other than ACCEPTING, accept
and reject both return the order unchanged with business status 200 — no state moves and no error is
raised. Treat acceptStatus = ACCEPTING as the precondition and re-read the returned order rather than
assuming the call took effect.

orderStatus stays PROCESSING for the whole stretch from the deposit landing to collection finishing,
so it cannot tell you where in this sequence an order is. Branch on whiteListStatus and acceptStatus.

An order that is not gated skips the middle three rows: compliance passes and acceptStatus goes
straight to ACCEPTING.

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

4.5 Refund attribution

A refunded order carries who refunded it and why. The same two fields appear on the reject response, on
GET /v2/stable/collect/order-status and on COLLECT_ORDER_UPDATED.

Field	Type	Meaning
`refundBy`	string \| null	`MERCHANT` for a refund you triggered with `POST /v2/stable/collect/order/reject`, `BPN` for one the platform triggered on its own. `null` while no refund has been initiated
`refundReason`	string \| null	The reason. Your `refundReason` is echoed back verbatim; a platform refund carries the platform's own reason

The platform can refund without you calling reject — a compliance decision, for example — so branch on
refundBy rather than assuming every refund is yours.

4.6 `acceptStatus`

Value	Meaning	What you do
`INIT`	Not acceptable yet — compliance and, where it applies, the whitelist gate are still in front of it	Wait
`ACCEPTING`	Acceptable now. The only state in which accept and reject take effect	Call accept, or reject to refund
`ACCEPTED`	You accepted; collection follows	Wait for `orderStatus = SUCCESS`
`REJECTED`	You rejected; a refund follows — see 4.5	Read `refundBy` / `refundReason`

orderStatus is PROCESSING for INIT, ACCEPTING and ACCEPTED alike, so acceptStatus is what
tells you whether the order is waiting on you. See 3.4 for the order of operations.

4.7 Reading the payer behind a gated deposit

GET /v1/wallet/deposit-whitelist/cases/{transactionId} returns the whitelist gate of one deposit in a
single call — the gate status, the receiving sub-wallet, and payerWhitelist, the payer's Travel Rule
record behind it.

Part of the response	What it gives you
`whiteListStatus`, `creditStatus`, `failMessage`	The gate itself, and why it was sent back
`fromAddress`, `network`, `memo`, `amount`, `currency`, `txHash`	The deposit. The first three are frozen and a submission cannot change them
`walletId`, `walletName`, `walletType`, `autoCollection`, `walletStatus`	The receiving sub-wallet
`payerWhitelist`	Source address, Travel Rule details, and the address-side `status` / `failMessage`. `null` until payer details have been submitted or matched

Use it when you need the payer side of a gated deposit. GET /v1/wallet/transaction/detail carries
the transaction and its whiteListStatus, but not the payer's whitelist record.

transactionId is the deposit transaction id — on a collection order, the same value as the order's
orderId. A deposit that never went through the whitelist gate has no case and returns 10000100.

5. Webhooks

Deduplicate on eventId. Full catalogue: Event catalogue.

5.1 Reading the whitelist gate

There is no dedicated whitelist webhook. The gate rides on the order webhook you already consume, as
data.whiteListStatus.

Webhook	Gate — payer details needed	Order finished
`COLLECT_ORDER_UPDATED`	`orderStatus = PROCESSING` with `whiteListStatus` `init` or `rejected`	`orderStatus = SUCCESS`
`DEPOSIT_ORDER_NOTIFICATION`	`status = PROCESSING` with `whiteListStatus` `init` or `rejected`	`status = SUCCESS`, normally with `whiteListStatus = approved`

`whiteListStatus`	What it means	What you do
`init`	This deposit needs payer details; funds are in the unavailable balance	Call submit with the Travel Rule details. Do not change the payer address, network or memo
`pending`	Submitted, under review	Wait
`rejected`	Details were rejected; funds still unavailable	Read `failMessage` on the transaction, correct it, submit again
`approved`	Review passed; funds are in the receiving wallet's available balance	Update the balance you show. Not the end of the order

A gate only appears for a deposit that actually goes through the whitelist flow. A deposit from a
source address that is already ACTIVE never shows one.

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, and the refund fields of 4.5 travel on the same payload.

Order completion is signalled only by COLLECT_ORDER_UPDATED with orderStatus = SUCCESS. A gate
(PROCESSING with init or rejected) never means the order is finished, and approved on its own does
not close it either.

data.acceptStatus rides on the same payload. The delivery that carries acceptStatus = ACCEPTING is the
one that hands the order back to you — see 3.4.

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

5.4 Typical sequences

Address not whitelisted yet (Path B)

COLLECT_ORDER_UPDATED at PROCESSING with whiteListStatus = init → you submit

optionally COLLECT_ORDER_UPDATED at PROCESSING with whiteListStatus = rejected → you submit again

whiteListStatus reaches approved — funds credited to the receiving wallet

COLLECT_ORDER_UPDATED with acceptStatus = ACCEPTING → you call accept, or reject to refund

COLLECT_ORDER_UPDATED with acceptStatus = ACCEPTED → collection runs

final COLLECT_ORDER_UPDATED at orderStatus = SUCCESS

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

no gate at any point

COLLECT_ORDER_UPDATED with acceptStatus = ACCEPTING → you call accept

one or more further 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
`GET`	`/v1/wallet/deposit-whitelist/cases/{transactionId}`	A / B	Whitelist gate of one deposit, including the payer's Travel Rule record — see 4.7

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/transaction/list`	Supports `whiteListStatus=init\|pending\|approved\|rejected` as a filter
`GET`	`/v1/wallet/transaction/detail`	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 and the refund fields of 4.5 now sit next to orderStatus in the order payload.

Method	Path	Purpose
`POST`	`/v2/stable/collect/order/accept`	Accept a collection order — only while `acceptStatus = ACCEPTING`, see 3.4
`POST`	`/v2/stable/collect/order/reject`	Reject a collection order and refund the payer — see 7.5
`GET`	`/v2/stable/collect/order-status`	One order, including `whiteListStatus` and the refund fields

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/transaction/list` with `whiteListStatus`

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:

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

status 200 only means the submission was accepted. The channel may reject it on the spot and still
answer 200, so read whiteListStatus and failMessage rather than the outer status:

{
  "requestNo": "uuid",
  "status": "PROCESSING",
  "whiteListStatus": "rejected",
  "failMessage": "G20011: Invalid IP address",
  "transactionIds": ["20573580428712136704"]
}

failMessage carries a reason only when whiteListStatus is rejected; otherwise it is an empty string.
A parameter or business failure looks different — status 500 with an outer code and msg and no
data, so there is no data.failMessage to read.

7.4 Transaction detail

GET /v1/wallet/transaction/detail → data

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

7.5 Reject a collection order

POST /v2/stable/collect/order/reject, header Idempotency-Key

{
  "orderId": "WT...",
  "requestId": "req_...",
  "refundReason": "Customer cancelled"
}

Response — the refund-related part of the order object:

{
  "orderId": "WT...",
  "orderStatus": "REFUNDING",
  "acceptStatus": "REJECTED",
  "refundBy": "MERCHANT",
  "refundReason": "Customer cancelled"
}

GET /v2/stable/collect/order-status and COLLECT_ORDER_UPDATED carry the same fields. A
platform-initiated refund looks identical but with refundBy BPN and a platform-supplied
refundReason.

7.6 Accept a collection order

Only once acceptStatus = ACCEPTING — see 3.4.

POST /v2/stable/collect/order/accept, header Idempotency-Key

{
  "orderId": "WT...",
  "quoteId": "9dcd762a6399451f9672098c201a0517",
  "requestId": "req_..."
}

Response — the order moves on:

{
  "orderId": "WT...",
  "orderStatus": "PROCESSING",
  "acceptStatus": "ACCEPTED"
}

quoteId must be the one carried on the order when acceptStatus turned ACCEPTING; the quote is
refreshed at that moment and expires at quote.expireTime. An expired or mismatched quote is rejected
with 10000064.

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
`10000064`	The quote on an accept call has expired or does not match the order
`10000007`	The order does not exist, or `requestId` does not match the one already on it

9. Integration checklist

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

Subscribed to COLLECT_ORDER_UPDATED; on Path A also to WALLET_ADDRESS_UPDATED

Booking a deposit is not conditional on a whitelist gate — an already whitelisted address never
shows one

A whitelist rejection (whiteListStatus = rejected) and an order rejection (orderStatus = REJECTED)
are handled as different things

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

POST /v2/stable/collect/order/accept is called only once acceptStatus = ACCEPTING; on a gated
order that is after the whitelist clears and the funds are credited — never before

An accept or reject sent earlier is a silent no-op — the returned order is re-read rather than
assumed accepted

Refunds are attributed with refundBy — a BPN refund can arrive without you calling reject

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

Pending work is found with GET /v1/wallet/transaction/list?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#

3.4 Whitelist first, then accept#

4. Status fields#

4.1 Order status / orderStatus#

4.2 whiteListStatus#

4.3 creditStatus#

4.4 Source address status (Path A only)#

4.5 Refund attribution#

4.6 acceptStatus#

4.7 Reading the payer behind a gated deposit#

5. Webhooks#

5.1 Reading the whitelist gate#

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#

7.5 Reject a collection order#

7.6 Accept a collection order#

8. Error codes#

9. Integration checklist#