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
| Field | Meaning and verification |
|---|---|
bizType | For collection, the fixed value is collect。 |
mchId | Must match the merchant associated with the local order. |
platformOrderNo | Platform order number; associate it with the local payment record. |
outTradeNo | The merchant order number supplied when creating the order. |
merchantOrderNo | Compatibility field with the same value as outTradeNo. |
transactionId | Channel transaction reference; the platform order number is used if the channel does not provide one. |
amount | Amount in minor units (fen), for example the string 1000。 |
amountYuan | Amount in yuan with two decimal places, for example 10.00。 |
currencyCode | Currency, for example CNY。 |
orderStatus | Order status; the successful notification example uses the string 1。 |
tradeState | For successful collection, the value is SUCCESS。 |
returnCode | 00 indicates business success. |
successTime | Success timestamp in the format yyyy-MM-dd HH:mm:ss。 |
notifyTime | Timestamp for this notification, using the same format. |
sign | Business 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
- Read the JSON, preserve the original field values and extract the
sign。 - Prefer
CALLBACK_SECRET; if no separate callback key is configured, useMD5_SECRET。 - Exclude sign and empty fields, concatenate fields by ascending ASCII field name, append
&key=YOUR_KEY, calculate lowercase MD5 and compare. - After signature verification, check the merchant number, business type, merchant order number and platform order number to locate the actual local order.
- 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.
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
- Validate and locate the orderVerify the signature, amount and currency, then locate the same merchant payment record.
- Update state within a transactionLock the order or use a conditional update; do not book the payment again for a notification already processed successfully.
- Persist a unique fulfillment taskUse an order-specific unique key to record the code delivery, credit or shipment task.
- 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 rulesThis 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 ↗