Sync Callback

Updated: 8/3/26, 7:50:02 PM

Overview

The Sync Callback redirects the user's browser (not the merchant server) back to the merchant's returnUrl after a payment completes. The redirect URL appends order key parameters to the merchant returnUrl and is signed with the platform private key; the merchant verifies it with the platform public key to confirm the redirect is trustworthy.

Key differences from Async Callback:

Dimension	Sync Callback	Async Callback
Receiver	Merchant page (browser)	Merchant server
Delivery	Browser 302 redirect, params in URL query	Server HTTP POST (JSON) or MQ push
Timing	Browser returns after user pays	Immediately after order status change
Reliability	Once, no retry (user may close browser)	16 increasing retries
Verification	Verify query params with platform public key	Verify payload with platform public key
Purpose	Show "payment success" page / guide user back to merchant	Process order status changes

Sync callback is NOT authoritative for payment success

The sync callback depends on browser behavior: the user may close the page, lose network, or crash the browser, causing the redirect to be lost or duplicated. The final order status must come from the async callback or the query API. Merchants should not persist settlement data based solely on sync callback parameters.

Flow

1. The merchant passes returnUrl when creating the order (Create Payment / Gateway Pre-pay).
2. The platform initiates payment; only Alipay PC/WAP web payment sets the channel's sync return URL to the platform H5 result page {paymentGatewayBaseUrl}/pay-result/{tradeNo}.
3. After payment completes, the channel brings the user's browser back to the platform result page.
4. The result page queries the authoritative order status by tradeNo via the platform unsigned API.
5. When status is paid and the order has a merchant returnUrl, the platform generates a signed redirect URL (order params appended to returnUrl).
6. The result page auto-redirects after a 3-second countdown; without returnUrl or when not paid, it shows the platform result end page.
7. The merchant page verifies the signature first, then shows the result; the final order status comes from the async callback.

Redirect Parameters

The redirect URL = merchant returnUrl + query parameters. If returnUrl already has query params, the platform appends with &; values are URL-encoded.

Param	Type	Description
code	int	Status code (0 = success)
msg	string	Status message
tradeNo	string	Trade number (platform-generated, authoritative)
orderNo	string	Platform order number (omitted when empty)
bizOrderNo	string	Merchant order number (omitted when empty)
status	string	Order status (always paid for sync redirect)
amount	long	Order amount in cents (omitted when empty)
sign	string	Platform RSA signature (Base64, URL-encoded)

Redirect URL example:

https://merchant.example.com/return?code=0&msg=success&tradeNo=T2024120112345700001&orderNo=P2024120112345700001&bizOrderNo=ORDER20241201001&status=paid&amount=100&sign=Base64%20signature

Signature Verification

The merchant must verify the sign parameter to confirm the redirect was issued by the DaxPay platform and the params were not tampered with. The rules are identical to the async callback:

1. Collect all query parameters from the URL.
2. Remove the sign parameter.
3. Exclude parameters with empty values.
4. Sort the remaining keys by ASCII ascending order.
5. Join as key1=value1&key2=value2 (use the URL-decoded values).
6. Verify with the platform public key using SHA256withRSA.

See Signature Mechanism for code examples.

Notes

Always rely on the async callback

The sync callback is only for "returning the user to the merchant page and showing the result after payment". It is not the basis for persisting order status. The user may close the browser (redirect lost) or revisit the page (duplicate redirect). Always rely on the async callback or the query API.

1. Limited channel coverage: Only Alipay PC/WAP web payment truly completes the "channel redirect → platform result page → signed redirect to merchant" loop. For WeChat/UnionPay/Douyin JSAPI scenarios, the front-end H5 determines payment success by polling and then redirects; channels without sync-return integration do not honor returnUrl (merchants may poll themselves).
2. Redirect only when paid: failed / closed / expired do not redirect to the merchant; the user sees the corresponding status and a "Close page" button on the platform result page.
3. No redirect when status not ready: after payment, the channel callback may be briefly delayed. The platform queries after a 3-second countdown buffer; if the order is still not paid, the platform does not generate a redirect URL and does not redirect — it stays on the result page rather than bare-redirecting to an unsigned returnUrl (merchants cannot verify unsigned URLs, and it would hide real problems).
4. No auto redirect on re-entry: re-scanning or revisiting an already-paid order only shows the success card, without auto redirect; the user may click "Back to merchant" to redirect manually.
5. PC aggregate guide pages do not redirect: PC pages that only show a QR code do not redirect to the merchant returnUrl after payment (payment happens on the phone, which is the redirecting device), avoiding duplicate redirects from both phone and PC.
6. Session-level idempotency: auto-redirect happens only once per browser session (front-end sessionStorage marker). Switching devices, clearing cache, or incognito mode may trigger it again — there is no server-side idempotency, so merchants should tolerate duplicate redirects.
7. Getting tradeNo: the tradeNo in the redirect params corresponds to NormalPayResult.tradeNo in the payment initiation response. Save the value from the payment initiation response; it may be empty in pre-pay/early query stages (the trade is created when payment is initiated).
8. No attach: the sync callback carries a minimal parameter set and does not include the merchant extension param attach. For the full order snapshot (attach, channel, pay time, etc.), rely on the async callback.
9. returnUrl concatenation: if returnUrl already has query params, the platform appends with &; empty fields are omitted (e.g., orderNo/bizOrderNo/amount may be absent). The merchant page must tolerate unknown or missing params.
10. Platform config: the platform must configure paymentGatewayBaseUrl (Platform Config → Basic Config); otherwise the Alipay sync-return URL cannot be generated.
11. Always verify the signature: the redirect URL can be forged by anyone (returnUrl is public). Verify the signature before processing to prevent forged redirects misleading users.

Merchant Integration Steps

1. Pass returnUrl when creating the order (returnUrl param of Create Payment or Gateway Pre-pay, max 200 chars).
2. Save the tradeNo from the payment initiation response (for reconciliation and active querying).
3. After the user pays, the browser is brought back to the merchant returnUrl; parse the query parameters.
4. Verify the signature with the platform public key first, then show the order result.
5. The final order status comes from the async callback or active querying; the sync callback is only a page guide.

Docs for AI Assistants

LLM-friendly document formats for ChatGPT, Claude, Cursor and other AI tools to read and understand DaxPay docs.

llms.txt — Site index, page list with summaries for quick lookup
llms-full.txt — Full docs merged, complete content in one file for bulk AI input