Asynchronous notifications

Payment callbacks: signature verification, order checks and idempotent fulfillment

Callbacks may arrive late or more than once. Your server must receive JSON, verify the signature, check the order and reliably persist the successful payment state before sending the result into a fulfillment workflow that can be retried safely.

Contents

When notifications reach your server

After receiving a successful payment notification from the channel and updating the collection order, the platform asynchronously sends a request to the order's notifyUrl using POST,Content-Type set to application/json. If the order has no notification URL, the merchant's default URL is used; your order request should still supply the required notifyUrl。

The notification endpoint must be publicly accessible and must not depend on a browser login session. You receive the standard 稳付pay format and do not need to parse raw upstream parameters. A browser success page or customer screenshot cannot replace backend verification.

The 15 fields in a standard notification

FieldMeaning and verification
bizTypeFor collection, the fixed value is collect。
mchIdMust match the merchant associated with the local order.
platformOrderNoPlatform order number; associate it with the local payment record.
outTradeNoThe merchant order number supplied when creating the order.
merchantOrderNoCompatibility field with the same value as outTradeNo.
transactionIdChannel transaction reference; the platform order number is used if the channel does not provide one.
amountAmount in minor units (fen), for example the string 1000。
amountYuanAmount in yuan with two decimal places, for example 10.00。
currencyCodeCurrency, for example CNY。
orderStatusOrder status; the successful notification example uses the string 1。
tradeStateFor successful collection, the value is SUCCESS。
returnCode00 indicates business success.
successTimeSuccess timestamp in the format yyyy-MM-dd HH:mm:ss。
notifyTimeTimestamp for this notification, using the same format.
signBusiness signature; exclude this field from its own signature calculation.

All fields in the notification example are strings. Preserve their received values for verification, especially 00 and 10.00; do not reformat, remove zeros or cast values to numbers before verifying the signature.

Verify the signature before checking the order and payment result

  1. Read the JSON, preserve the original field values and extract the sign。
  2. Prefer CALLBACK_SECRET; if no separate callback key is configured, use MD5_SECRET。
  3. Exclude sign and empty fields, concatenate fields by ascending ASCII field name, append &key=YOUR_KEY, calculate lowercase MD5 and compare.
  4. After signature verification, check the merchant number, business type, merchant order number and platform order number to locate the actual local order.
  5. Check the amount in fen, currency and successful payment state before entering idempotent processing.

Do not deliver based only on returnCode=00 nor orderStatus=1 . The signature, order identity, amount, currency and successful state must all pass verification. Stop fulfillment and record an exception if any check fails.

The rules for the compatibility header X-Plat-Signature must be confirmed separately with the technical team. This page uses the standard business signature in the Body, rather than calculating MD5 directly over the complete raw JSON.

Python verification and business workflow example
import json
import os
from wenfupay_collect_sign import verify_collect_notification

try:
    notice = json.loads(raw_request_body)
except (ValueError, UnicodeDecodeError):
    return http_response(400, "INVALID_JSON")
if not isinstance(notice, dict):
    return http_response(400, "INVALID_JSON_OBJECT")
verified = verify_collect_notification(
    notice,
    api_secret=os.environ["MD5_SECRET"],
    callback_secret=os.environ.get("CALLBACK_SECRET"),
)
if not verified:
    return http_response(400, "INVALID_SIGNATURE")

# Business-specific pseudocode: implement these durable operations.
with database_transaction():
    order = lock_order(notice["outTradeNo"])
    match_merchant_currency_and_amount_in_cents(order, notice)
    require_documented_success_fields(notice)
    record_payment_once(order, notice["platformOrderNo"])
    enqueue_fulfillment_once(order)

# Only after successful durable acceptance:
return http_response(200, "OK", content_type="text/plain")

The business functions illustrate the workflow and must be connected to your own orders and database. Do not acknowledge success before resolving persistence failures, invalid signatures or amount mismatches. After verification, a previously received and reliably persisted duplicate notification can return OK。

Record payment and fulfill each order only once

  1. Validate and locate the orderVerify the signature, amount and currency, then locate the same merchant payment record.
  2. Update state within a transactionLock the order or use a conditional update; do not book the payment again for a notification already processed successfully.
  3. Persist a unique fulfillment taskUse an order-specific unique key to record the code delivery, credit or shipment task.
  4. Acknowledge after committingReturn OK once the state and task are reliably saved; fulfillment can continue with retries.
Receive notification
  Invalid signature: reject processing; do not acknowledge success
  Merchant, order, amount or currency mismatch: record an exception; do not fulfill
  Begin database transaction
    Look up and lock the local order
    If not already successful: update the successful payment state
    Ensure a fulfillment task exists; business unique key = local order ID
  Commit database transaction
  Return HTTP 200 with plain-text OK

Fulfillment task
  If the business unique key has already been fulfilled: finish
  Otherwise fulfill safely once and record the result
  Temporary failure: retain the task and retry under the business rules

This is business pseudocode, not a directly executable transaction. If delivery cannot be completed within the same transaction, use durable tasks and unique fulfillment records so that a paid order is not left undelivered forever after a process restart.

Return OK correctly and handle retries

A successful acknowledgement requires both HTTP 200 and a response Body containing success、ok nor OK. Return plain-text OK, without a login page, HTML template or the framework's default JSON wrapper.

Also return OK for a duplicate notification confirmed as already processed. If the database is unavailable, signature verification fails or business checks do not pass, do not acknowledge success merely to stop retries.

Failed notifications are retried asynchronously, with at most 3 delivery attempts in total, including the initial attempt; after the first two failures, retries occur approximately 60 seconds and 300 seconds later. Retries are neither unlimited nor three additional sends after the initial attempt.

Query orders to recover missing notifications

The specification defines notifications after successful payment. Do not assume that failures, closures or expirations are always pushed. The backend needs to query orders that remain pending, time out during creation or encounter notification processing errors.

When a query confirms success, enter the same idempotent fulfillment workflow used by callbacks; do not create a separate delivery path that skips amount checks. Confirm the query amount convention during onboarding before converting and comparing it. Keep an unknown result pending verification.

Integration testing should cover at least duplicate notifications, a query before a callback, a callback before a query, temporary database failures and fulfillment retries after payment success. Technical staff will help confirm the configuration and exception handling.

This article is based on the 稳付pay integration specification. Return to the integration overview or see the order creation and query fields。

Confirm integration for your business scenario

Describe your products, order volume, payment methods and settlement needs to confirm the APIs, movement of funds and exception handling item by item.

Contact 稳付pay ↗