Wallet · PaymentLink

Payment Links let a merchant collect supported stablecoins through a hosted payment page. This guide covers creation, status handling, webhook processing, and reconciliation. Withdrawal flows are outside this guide.

Integration flow

Configure merchant credentials, a Payment Link webhook destination, and an eligible Collection Sub wallet.

Query the supported currencies and networks before creating a link.

Create a One-Time or Permanent Payment Link with a merchant-generated requestId.

Store paymentId, paymentLink, requestId, recipient wallet, amount, and link type.

Present the hosted link to the payer.

Treat processing as pending. Confirm collection only when the order reaches completed.

Process webhooks idempotently and reconcile nonterminal records through the list API.

Create a Payment Link

Use POST /v1/stable/collect/create-payment-link.

Merchant request ID

Use requestId for new integrations.

userOrderNo is deprecated. When requestId is blank, the platform falls back to userOrderNo; when both are nonblank, requestId takes precedence.

A detected duplicate returns ODR00000040; the original result is not replayed.

After an unknown result, query with the original requestId. Do not change the ID merely to bypass a duplicate error.

Permanent payment child orders may not inherit the parent link's requestId. Use the child paymentId as the payment identity and referencePaymentId as the parent relationship.

One-Time links

A One-Time link is created in init. It becomes active when activated, and its validity window starts from activation.

Required fields depend on the pricing mode:

Mode	Required amount fields
Fiat-priced	`fiatCurrency` and `fiatAmount`
Crypto-priced	`cryptoAmount` and one concrete `supportCurrency`

paymentValidTime is required for One-Time links and is expressed in minutes.

Permanent links

A Permanent link is reusable and is created in active. Each actual payment creates a separate child order. Keep the parent link and child payments as different records.

Query and recovery

Use POST /v1/stable/collect/payment-links.

Query by paymentId to recover one known link or payment record. When paymentId and referencePaymentId are both supplied, they are combined with AND.

Query by requestId to recover an uncertain create result.

primaryOrderOnly defaults to true and returns primary Payment Links only. Set it to false to include primary links and actual payment child records.

Query by referencePaymentId to page actual payment child records for a Permanent parent link. When supplied, primaryOrderOnly is ignored.

An empty result while creation may still be in flight is not proof that creation failed.

startTime and endTime filter record creation time, not payment or fund-transfer completion time.

Requery records that remain nonterminal after the original creation-time window.

Status model

One-Time order

Status	Terminal?	Meaning	Merchant action
`init`	No	Created but not activated	Present the link and wait
`active`	No	Activated and payable	Track the payment
`processing`	No	Payment matched; fund transfer is incomplete	Wait and query again; do not credit as final
`completed`	Yes	Every required merchant fund transfer succeeded	Confirm collection idempotently
`expired`	Not always	Payment window ended without a matched payment	Stop directing new payment and keep boundary cases under review

An address-risk rejection can keep an order in processing for manual handling. Do not infer a terminal outcome from elapsed time.

Permanent link and payment child

The parent Permanent link remains active. Each actual payment creates a child order:

A child order's referencePaymentId points to the Permanent parent link. Use the child paymentId for per-payment booking and deduplication.

Time fields

All timestamps are Unix epoch milliseconds.

Field	Meaning
`createTime`	Link or payment-record creation time
`effectiveTime`	One-Time link activation time
`expiresTime`	Activation time plus `paymentValidTime`

Creation time does not represent payment completion or fund-transfer completion. Do not calculate a final collection result from timestamps.

Payment Link webhook

Event type: PAYMENT_LINK_UPDATED.

One-Time creation, activation, expiry, and final completion can emit status notifications.

Entering processing does not by itself emit a Payment Link status webhook.

A Permanent parent emits its active state; each payment child emits completed only after all required fund transfers succeed.

Webhooks may be duplicated or delayed. Deduplicate by eventId, then apply business idempotency by the actual payment paymentId.

Do not let a late nonterminal event overwrite a stored completed result.

Verify the webhook signature using the raw request body and the documented authentication headers.

Reconciliation

For One-Time links:

Page through records by overlapping creation-time windows.

Deduplicate records by paymentId.

Persist and requery init, active, and processing records until a terminal business decision is available.

Book the collection only at completed.

For Permanent links:

Store each payment child's paymentId and referencePaymentId from the webhook.

Query a known child by its own paymentId.

Reconcile and book each child independently; never use the parent paymentId as the identity of every payment.

Error handling

Situation	Action
Create timeout or unknown result	Query with the original `requestId`, then retry recovery with backoff
Duplicate request ID	Query the original request; do not generate a new ID just to bypass the error
Long-running `processing`	Query again and contact the platform if it remains unresolved
Expired order with a detected payment	Follow query and webhook results; do not assume automatic credit or refund
Duplicate or late webhook	Deduplicate events and prevent status regression

Wallet · PaymentLink

Integration flow#

Create a Payment Link#

Merchant request ID#

One-Time links#

Permanent links#

Query and recovery#

Status model#

One-Time order#

Permanent link and payment child#

Time fields#

Payment Link webhook#

Reconciliation#

Error handling#