Webhook Notifications

StablePay pushes critical payment, refund, subscription, and invoice events asynchronously to your callback URL configured in the Merchant Dashboard via Webhooks. This page summarizes Webhook event types, request headers, signature verification requirements, and recently added adaptations for the risk control freeze status.

Configuring Webhooks in the Merchant Portal

Before your server can receive Webhook notifications, you need to create an API store and configure the callback address in the Stores and Developers page.

Step 1: Create an API Store

Open the Stores and Developers page.
Click Create Store.
Select API as the channel type.
Fill in the store name and domain according to your actual business information.
Submit the application and wait for StablePay review.

Create an API store in the Stores and Developers page

Step 2: Configure Webhook after Store Activation

Once the store status changes to Enabled:

Return to the Stores and Developers page.
Open the action menu for the corresponding store.
Click Webhook.
Fill in your Webhook callback URL and save.
If needed, you can also click Keys in the same action menu to create the API Key and Secret Key required for server-side integration.
If the validity period is set to 0 days, it means the key is valid indefinitely.

Create keys and configure Webhook URL in the action menu of an enabled store

It is recommended to use an HTTPS server address accessible from the StablePay public network as the Webhook callback address, separate from browser pages or frontend routes. Please do not use frontend page URLs directly as Webhook target addresses.

Event Types

Category	Event Type
Payment	`payment.completed`, `payment.failed`, `payment.expired`, `payment.cancelled`
Refund	`refund.succeeded`, `refund.failed`
Subscription	`subscription.created`, `subscription.trialing`, `subscription.active`, `subscription.past_due`, `subscription.canceled`, `subscription.updated`, `subscription.incomplete_expired`
Invoice	`invoice.created`, `invoice.paid`, `invoice.payment_failed`

Webhook Request Headers

Header	Description
`Content-Type`	Fixed `application/json`
`User-Agent`	`StablePay-Webhook/1.0`
`X-StablePay-Signature`	Lowercase hex signature of `{timestamp}.{nonce}.{raw_body}` using HMAC-SHA256
`X-StablePay-Timestamp`	Unix timestamp (seconds)
`X-StablePay-Nonce`	Random string (16-64 characters), included in signature calculation, unique per notification
`X-StablePay-Event-Type`	Event type, e.g., `payment.completed`
`X-StablePay-Event-ID`	Unique event ID for idempotency and deduplication

Signature Verification

Please use the raw request body bytes for verification; do not parse JSON and then re-serialize before verification. The signature string format is as follows:

sign_payload = {timestamp} + "." + {nonce} + "." + {raw_body}

Verification recommendations:

Read X-StablePay-Signature, X-StablePay-Timestamp, and X-StablePay-Nonce
Verify the timestamp is within 5 minutes of the current time
Verify the nonce length is 16-64 characters
Use your Secret Key to generate an HMAC-SHA256 of the signature string
Use constant-time comparison to verify the signature

For signature verification code examples, refer to Pre-integration Preparation.

Response and Retry

Your service must return HTTP 2xx within 30 seconds
Returns of 429 or 5xx will enter the retry queue; other 4xx responses will not retry by default
Maximum of 10 retries
It is recommended to use X-StablePay-Event-ID or the id field in the request body for idempotency and deduplication

payment.failed and frozen Status

StablePay has recently enhanced its risk control capabilities. After this update, when a payment order triggers high-risk control policies, funds may be temporarily frozen. Such scenarios typically involve suspected illicit activities, abnormal transactions, or other high-risk behaviors, requiring further review before confirming subsequent processing results. After this mechanism goes live, StablePay will continue to use the existing payment.failed webhook event type to notify merchant systems, but the callback will include a new payment status:

"status": "frozen"

This means data.object.status in payment.failed events now has at least two processing branches:

failed: Normal payment failure; handle according to existing failure logic
frozen: Risk control freeze; should not be treated as a normal payment failure

Depending on the channel or integration source, business extension fields may appear in metadata or as independent fields. Please refer to type, id, and the core status fields in data.object that are directly relevant to your business processing.

frozen Example Callback

{
  "id": "evt_1778818565572372433",
  "data": {
    "object": {
      "amount": 1,
      "status": "frozen",
      "currency": "USDT",
      "metadata": {
        "source": "api",
        "wc_order_id": "order_0b543c39"
      },
      "order_id": "order_0b543c39",
      "session_id": "20260515110100101649130000272078",
      "exchange_rate": ""
    }
  },
  "type": "payment.failed",
  "created_at": 1778818549
}

Handling Recommendations

When receiving a payment.failed event, please additionally check data.object.status:

When status = "failed", handle according to existing payment failure logic
When status = "frozen", we recommend marking the order as “Risk Control Frozen” or “Pending Risk Review”

For frozen scenarios, do not handle as a normal payment failure, and we do not recommend automatically performing the following actions:

Automatic order replenishment
Automatic delivery
Automatic release of service entitlements or access permissions

Event Examples

payment.completed

{
  "id": "evt_1778835561972546443",
  "type": "payment.completed",
  "created_at": 1778835561,
  "data": {
    "object": {
      "amount": 1,
      "status": "completed",
      "currency": "USDT",
      "order_id": "order_56929d9f",
      "session_id": "20260515110100101170210000082012",
      "exchange_rate": "",
      "source": "api"
    }
  }
}

payment.failed

{
  "id": "evt_1778834854265555041",
  "type": "payment.failed",
  "created_at": 1778834851,
  "data": {
    "object": {
      "amount": 1,
      "status": "frozen",
      "currency": "USDT",
      "order_id": "order_31509b43",
      "session_id": "20260515110100101170210000082010",
      "exchange_rate": "",
      "source": "api"
    }
  }
}

payment.expired

{
  "id": "evt_1778836650899324281",
  "type": "payment.expired",
  "created_at": 1778836650,
  "data": {
    "object": {
      "amount": 0,
      "status": "expired",
      "currency": "",
      "order_id": "order_d3ff11a8",
      "session_id": "20260515110100101170210000082011",
      "exchange_rate": "",
      "source": "api"
    }
  }
}

payment.cancelled

{
  "id": "evt_1770864227443530013",
  "type": "payment.cancelled",
  "created_at": 1770864227,
  "data": {
    "object": {
      "amount": 0,
      "status": "canceled",
      "currency": "",
      "order_id": "order_29",
      "session_id": "20260212110100101170210000028002",
      "exchange_rate": "",
      "source": "api"
    }
  }
}

Pre-integration Preparation

Getting Started

Payment API

Refund API

Subscription API

Invoice API

Configuring Webhooks in the Merchant Portal

Step 1: Create an API Store

Step 2: Configure Webhook after Store Activation

Event Types

Webhook Request Headers

Signature Verification

Response and Retry

payment.failed and frozen Status

frozen Example Callback

Handling Recommendations

Event Examples

payment.completed

payment.failed

payment.expired

payment.cancelled

​Configuring Webhooks in the Merchant Portal

​Step 1: Create an API Store

​Step 2: Configure Webhook after Store Activation

​Event Types

​Webhook Request Headers

​Signature Verification

​Response and Retry

​payment.failed and frozen Status

​frozen Example Callback

​Handling Recommendations

​Event Examples

​payment.completed

​payment.failed

​payment.expired

​payment.cancelled

​Related Pages

Configuring Webhooks in the Merchant Portal

Step 1: Create an API Store

Step 2: Configure Webhook after Store Activation

Event Types

Webhook Request Headers

Signature Verification

Response and Retry

payment.failed and frozen Status

frozen Example Callback

Handling Recommendations

Event Examples

payment.completed

payment.failed

payment.expired

payment.cancelled

Related Pages