Prepay Whitelist for Permanent Payment Link

Prepay whitelist for a Permanent payment link

POST /v1/stable/collect/payment-links/permanent/prepay-whitelist

The hosted payment page must call create-permanent-prepay first. clientId is the session id that page sends; the response echoes it. currency, network, and amount must equal that call. orderId is the paymentId from POST /v1/stable/collect/create-payment-link. walletId must equal that link's recipientAccountId.

Why whitelist

Crypto paid through this payment link is usable only after the payer details pass the deposit whitelist.

If you skip this call

The on-chain payment is still received, but it stays gated:

The collection order remains PROCESSING, with whiteListStatus init.

The funds sit in the unavailable balance of the receiving wallet. They cannot be withdrawn or converted.

If the payer has paid and the source address is not whitelisted yet, COLLECT_ORDER_UPDATED is sent with orderStatus PROCESSING and whiteListStatus init. After the whitelist is approved and the funds are credited, COLLECT_ORDER_UPDATED is sent with orderStatus SUCCESS.

Submit payer details after the payment arrives

Use this when whiteListStatus is init (never submitted) or rejected (resubmit).

Take transactionId from COLLECT_ORDER_UPDATED. Pass that value as {transactionId} on the submit call.

Call POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit with the payer details. Do not send the source address, network, memo, or transaction hash. Those come from the on-chain payment.

whiteListStatus becomes pending while the review runs.

On rejected, read failMessage and submit again. The order stays PROCESSING and the funds stay unavailable.

When the review passes, the funds move into the available balance of the receiving wallet. If the wallet auto-collects, the order can stay PROCESSING until that sweep finishes. COLLECT_ORDER_UPDATED with orderStatus SUCCESS is the completion signal.

Guide: Wallet · Deposit whitelist

Which call

Link type	Endpoint	When
`onetime`	`POST /v1/stable/collect/payment-links/onetime/prepay-whitelist`	After `POST /v1/stable/collect/create-payment-link`
`permanent`	`POST /v1/stable/collect/payment-links/permanent/prepay-whitelist`	After the hosted payment page has called `create-permanent-prepay`

Use the endpoint that matches the link's paymentLinkType. A mismatch returns ODR00000041.

This call covers this payment link only. To reuse one payer for every deposit into a sub-wallet, use POST /v1/wallet/deposit-whitelist/wallets/{walletId}/profile.

travelRule uses the same payer fields as Address Book / submit:

`correspondentType`	Required inside `travelRule`
`ENTITY`	`fullName`, `countryCode`, `companyAddress`
`INDIVIDUAL`	`firstName`, `lastName`, `birthday` (`yyyy-MM-dd`), `countryCode`, `residentialAddress`

Do not send walletAddress, network, memo, symbol, or txHash inside travelRule. Do not send countryInfo.

Authentication is the same as the other Stable collect APIs.

Failures

Business failure uses status 500.

`code`	When
`ODR00000041`	`paymentLinkType` is not `permanent`; `walletId` is not the link's recipient account; `clientId`, `currency`, `network`, or `amount` is missing; the order is not owned by the caller
`10000103`	A `travelRule` value is not accepted. An unrecognised `countryCode` returns this code.

amount is a decimal string. A JSON number is accepted. It must equal the amount on that create-permanent-prepay call.

Example

{
  "orderId": "PAY2025101507677652572380042240",
  "walletId": 10086,
  "clientId": "client-session-uuid",
  "currency": "USDT",
  "network": "ETH",
  "amount": "100.00",
  "travelRule": {
    "walletLabel": "Payport Limited",
    "addressType": "STANDARD",
    "walletType": "VASP",
    "provider": "Binance",
    "correspondentType": "ENTITY",
    "fullName": "Payport Limited",
    "countryCode": "SG",
    "companyAddress": "Tampines Blk67, Singapore"
  }
}

Success data:

{
  "prepayId": 90001,
  "bizNo": "90001",
  "saved": true
}

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/jsonRequired

Example

{
  "orderId": "PAY2025101507677652572380042240",
  "walletId": 10086,
  "clientId": "client-session-uuid",
  "currency": "USDT",
  "network": "ETH",
  "amount": "100.00",
  "travelRule": {
    "walletLabel": "Payport Limited",
    "addressType": "STANDARD",
    "walletType": "VASP",
    "provider": "Binance",
    "correspondentType": "ENTITY",
    "fullName": "Payport Limited",
    "countryCode": "SG",
    "companyAddress": "Tampines Blk67, Singapore"
  }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

application/json

Bodyapplication/json

Example

{
    "status": 200,
    "msg": "OK",
    "code": null,
    "traceId": "a1b2c3d4e5f6",
    "data": {
        "prepayId": 90001,
        "bizNo": "90001",
        "saved": true
    }
}

Prepay Whitelist for Permanent Payment Link

Prepay whitelist for a Permanent payment link#

Why whitelist#

If you skip this call#

Submit payer details after the payment arrives#

Which call#

Failures#

Example#

Request

Request Code Samples

Responses

Prepay whitelist for a Permanent payment link

Why whitelist

If you skip this call

Submit payer details after the payment arrives

Which call

Failures

Example