PaymentLink Notification

Webhook Status Flow

One-Time Payments

init -> active -> processing -> completed, or active -> expired.

Permanent Payment Links

Parent link: created -> active -> remains active and reusable.

Each payment: payment matched -> child payment record (paymentId, referencePaymentId) -> processing -> completed.

A child becomes completed only after all required merchant fund transfers succeed.

No order-status notification is emitted only for entering processing; completion is notified when the child becomes completed.

Amount tolerance

data.amountTolerance reports the tolerance band that was in effect for the order.

NONE — the payment had to match the expected amount exactly.

PERCENTAGE — a payment within percentage above or below the expected amount was accepted.

FIXED — a payment within fixedAmount above or below the expected amount was accepted.

The band is two-sided: both underpayment and overpayment inside the band are matched. Tolerance applies to One-Time links only.

amountTolerance is present on Payment Links created from this release onward. Links created earlier omit the field entirely; treat an absent amountTolerance as exact-amount matching.

Deposit addresses

data.addressList carries the deposit addresses that were pre-allocated for the order, one entry per eligible chain. It is emitted only when address pre-allocation is enabled for the merchant; every other notification omits the field, and the payer obtains the address through the hosted checkout link.

The list is the same set returned by POST /v1/stable/collect/create-payment-link, and it is repeated on every notification for the order rather than only the first one. When an entry carries a memo, the payer must include it or the deposit cannot be matched to this order.

Request

Header Params

Body Params application/json

Example

{
    "eventId": "string",
    "eventType": "PAYMENT_LINK_UPDATED",
    "timestamp": 0,
    "data": {
        "paymentId": "string",
        "referencePaymentId": "sample_parentPaymentId",
        "requestId": "sample_requestId",
        "userOrderNo": "string",
        "productRemark": "string",
        "recipientName": "string",
        "recipientAccountId": "string",
        "fiatCurrency": "string",
        "fiatAmount": "string",
        "cryptoCurrency": "string",
        "cryptoAmount": "string",
        "quotePrice": "string",
        "supportCurrency": "string",
        "supportNetwork": "string",
        "payerInfo": {
            "payerNameUnavailable": true
        },
        "returnUrl": "http://example.com",
        "status": "init",
        "paymentLinkType": "permanent",
        "paymentValidTime": 1,
        "paymentLink": "http://example.com",
        "effectiveTime": 0,
        "expiresTime": 0,
        "createTime": 0,
        "addressList": [
            {
                "address": "sample_address",
                "coin": "USDT",
                "network": "ETH",
                "name": "Ethereum (ERC20)",
                "memo": "123456789"
            }
        ],
        "amountTolerance": {
            "mode": "NONE",
            "percentage": 0.01,
            "fixedAmount": 0.5
        }
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

PaymentLink Notification

Webhook Status Flow#

One-Time Payments#

Permanent Payment Links#

Amount tolerance#

Deposit addresses#