Register Deposit Source Address

POST /v1/wallet/deposit-whitelist/addresses

The payer's source address must be registered and reviewed before the deposit can reach the
available balance of the receiving wallet. See the guide: Guides · Wallet · Deposit whitelist.

Registers one payer source address and submits it for review. Use this when you already know which address
the payer will send from.

The record cannot be edited after submission. If the review ends in FAILED, call
POST /v1/wallet/deposit-whitelist/addresses/{id}/disable and register a new record.

The response is PROCESSING: review is asynchronous. Poll
GET /v1/wallet/deposit-whitelist/addresses/{id} or listen for WALLET_ADDRESS_UPDATED.

Once the address is ACTIVE, deposits from it skip the whitelist flow entirely. They raise neither
DEPOSIT_WHITELIST_REQUIRED nor DEPOSIT_WHITELIST_CREDITED — the only webhook you get is the ordinary
DEPOSIT_ORDER_NOTIFICATION when the deposit completes.

Send the Idempotency-Key header. Retrying the same key after a timeout returns the first result instead of
creating a second address record.

Payer field rules

`correspondentType`	Mandatory fields	Must NOT be sent
`ENTITY`	`fullName`, `countryCode`, `companyAddress`	`firstName`, `lastName`, `birthday`, `residentialAddress`
`INDIVIDUAL`	`firstName`, `lastName`, `birthday` (`yyyy-MM-dd`), `countryCode`, `residentialAddress`	`fullName`

`walletType`	Also mandatory
`VASP`	`provider` — value must come from `GET /v1/wallet/deposit-whitelist/options`
`OTHERS`	`othersPleaseSpecify` (max 255 characters)
`SELF_HOSTED`	—

countryCode is an ISO 3166-1 alpha-2 code such as SG. countryInfo was withdrawn — the platform derives
the country name server-side. Sending it is unnecessary.

Error codes

Business failures return status 500 and an 8-digit code (WalletErrorCode).

`code`	Meaning
`10000100`	Transaction not found, or it does not belong to the caller
`10000101`	Deposit-whitelist review already completed for this deposit
`10000102`	Payer details incomplete
`10000103`	Field value not accepted, including an invalid `countryCode` or an unknown `provider`
`10000104`	Cannot submit right now — poll the status instead of editing and retrying immediately
`10000105`	Duplicate request
`10000106`	Source address cannot be supplied or changed when submitting for a received deposit

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: ********************

Header Params

Body Params application/json

Example

{
    "requestId": "b0f4c6a2-7d51-4c0e-9a2f-6f7c1e2d3b40",
    "walletLabel": "Payport Limited",
    "network": "BSC",
    "walletAddress": "0x3a1F8C4e2b6C8c9D7fE2B8b5a1d3C9A0bE12F345",
    "memo": "",
    "symbol": "USDC",
    "addressType": "STANDARD",
    "walletType": "VASP",
    "provider": "Binance",
    "othersPleaseSpecify": "",
    "correspondentType": "ENTITY",
    "fullName": "Payport Limited",
    "firstName": "Alex",
    "lastName": "Tan",
    "birthday": "1990-01-31",
    "countryCode": "SG",
    "companyAddress": "Tampines Blk67, Singapore",
    "residentialAddress": "12 Bedok North Ave 4, Singapore"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Bodyapplication/json

Examples

Success — entity payerFailure — payer details incompleteFailure — bad country code

{
  "status": 200,
  "code": null,
  "msg": "OK",
  "traceId": "Auto:bf288b9af2e04dff88e943f2dcaf2b03",
  "data": {
    "id": "10001",
    "status": "PROCESSING"
  }
}

Register Deposit Source Address