search

PayIn Webhook

hashtag
Webhook Delivery (PayIn)

Webhooks are sent only when the order status changes and only if url_callback is provided.

Confirmation counter updates do not trigger webhooks unless they also cause a status transition.

hashtag
Statuses that trigger a webhook

A webhook is dispatched on any order status change.

Merchants should distinguish between terminal settlement statuses and revisable statuses.

hashtag
Terminal settlement statuses

These statuses indicate that the payment outcome is finalized on-chain and will not change without a manual appeal:

  • paid

  • paid_over

  • paid_less

These statuses represent the final financial result of the PayIn.

hashtag
Revisable statuses (appeal-aware)

These statuses end the automatic flow, but may change later as a result of an appeal:

  • cancel

  • expired

Example appeal cases:

  • user sent funds after expiration

  • user paid but canceled the flow

  • user paid with incorrect amount or network

After a successful appeal, the order may transition to:

  • confirm_check

  • or directly to one of the paid* statuses

A new webhook will be sent on such transition.

hashtag
Transitional statuses (informational)

These statuses reflect the internal processing flow and may be skipped or delivered inconsistently depending on the network:

  • process

  • waiting_asset_select

  • pending

  • in_mempool

  • confirm_check

They should not be treated as final.

hashtag
Important notes

  • Webhooks are sent only on status transitions

  • Confirmation updates alone do not trigger webhooks

  • Each webhook payload includes:

    • current order state

    • previous status (prev_status)

  • Status order strictly follows the PayIn state machine

hashtag
Recommendation

Build merchant logic around paid / paid_over / paid_less and treat cancel and expired as potentially recoverable states.

hashtag
Request Example

PreviousGeneral InformationNextPayOut Webhook

Last updated