Top-up integration

WeChat top-up integration: customer payment, verification and account crediting

Here, a WeChat top-up means a user pays through WeChat to add funds to their account on your website or app. After 稳付pay confirms the payment result, it notifies your server; your system verifies the notification and credits the correct user's internal balance. Payment verification and balance accounting have separate responsibilities and must form a traceable, retryable workflow that never credits the same payment twice.

Contents

1. Define where funds are credited and who keeps the ledger

The user purchases credit within your website or app rather than adding funds to the WeChat wallet itself. 稳付pay integrates enabled WeChat payment channels, confirms payment results and sends order notifications. The merchant maintains user accounts, balance ledger entries and subsequent spending rules.

The top-up page should explain where credit can be spent, its validity and after-sales rules. If bonus credit is offered, record the actual payment and bonus separately rather than inferring the payment from the total credited balance. Spending, refunds and manual adjustments also need separate ledger entries with reasons and linked orders. Do not alter the accounts by deleting original top-up records.

Each top-up must be traceable from the user account to the merchant order and then the platform payment record. Do not allocate credit solely from a nickname, screenshot or payment with a matching amount, and do not confuse order created with account credited. This article does not imply that WeChat withdrawals or USDT exchange are available; the standalone payout API is not currently open.

2. A WeChat top-up in six steps

  1. User initiates a top-upThe user selects an amount; the merchant backend binds the user and generates a unique top-up order.
  2. Display the WeChat payment entryThe backend calls an enabled channel and displays the actual returned payment information.
  3. 稳付pay verifies paymentAssociate the original order and verify the successful payment result.
  4. Send a server-side callbackSend a standard payment notification to the merchant's configured notification URL.
  5. Merchant verifies the signature and orderCheck the signature, merchant, order, amount, currency and successful state.
  6. Credit the user balance atomicallySave the payment, unique balance ledger entry and balance update in one transaction, then acknowledge the notification.
Viewing the payment page is only one part of the process. Account crediting depends on reliable accounting by the merchant backend.

3. Fix the user and payable amount before order creation

Save the local top-up order first, including the user ID, merchant order number, payable amount, currency and a snapshot of the top-up rules. These are the merchant's own business records, not additional API parameters with the same names. Calculate amounts on the backend; do not let the frontend alter prices or let callbacks designate a different user.

Follow the collection order creation documentation to submit the merchant number, enabled channel code, order number, amount, notification URL, current millisecond timestamp and signature. Order amounts are in fen: 1000 represents 10.00 yuan. The WeChat aggregate code is 90001, but availability depends on merchant authorization and actual configuration.

The technical team confirms presentation methods, device restrictions and steps for WeChat personal QR and native channels during onboarding. Do not construct payment entries yourself. The official WeChat Pay Native product documentation helps explain QR payment terminology, but the 稳付pay aggregate MD5 protocol must not be used as though it were the official WeChat API.

4. Verify the callback before preparing to credit the account

Follow the standard callback documentation to verify sign in the Body. Prefer the configured CALLBACK_SECRET; use MD5_SECRET only if no separate callback key is set. Preserve notification values before verification: do not turn 00 into 0 or 10.00 into 10. Keep keys only on the server.

After verifying the signature, still check the merchant number, business type, original order number, platform order number, amount, currency and successful state. Callback amount is in fen and must match the local payable amount. Identify the user from the saved original order, never from arbitrary additional notification values.

Record unknown orders, amount mismatches and state conflicts as exceptions and contact technical staff for verification; do not credit automatically. A successful browser return or a user clicking Paid should only prompt the frontend to query its own backend for top-up progress.

5. Commit the unique ledger entry and balance update together

Apply a database unique constraint to top-up ledger entries, such as merchant plus top-up order as the unique business key. Update the order, ledger entry and user balance in the same transaction. Checking for existence before inserting does not stop two concurrent callbacks.

Verify the payment notification and check the original order
Begin database transaction
  Lock the top-up order and related account records
  If a successful top-up entry already exists for this order: do not credit again
  Otherwise: save the unique ledger entry, credit the correct user balance and update the top-up state
Commit transaction
Return HTTP 200 with plain-text OK

This is pseudocode for merchant accounting, not a new 稳付pay API. Roll back on database errors instead of acknowledging success first. Confirmed duplicate notifications may return OK; balance ledger entries, payment records and account updates must remain consistent. Query recovery must call the same function, rather than a separate crediting path that bypasses idempotency checks.

6. Handle timeouts, duplicate notifications and late payments

ScenarioCorrect handling
Order creation request times outQuery the original order number rather than immediately creating another top-up under a new number.
Balance did not increase after paymentCheck the payment, callback processing and local ledger entries; do not credit funds directly from a screenshot.
Duplicate callbacks or concurrent queriesUse the same accounting transaction protected by the unique ledger constraint.
A valid payment arrives after order expiryPreserve the payment fact and credit or refund under the agreed rules; do not ignore it.

Standard 稳付pay notifications have at most 3 delivery attempts in total, including the first. After the first two failures, retries occur approximately 60 seconds and 300 seconds later, so active query recovery is also needed. Confirm query response amount units during onboarding before converting and comparing. The official WeChat Pay callback and order query implementation guide also emphasizes that notifications may be delayed or missed and that server-side verification remains necessary after a browser return. This article does not copy its API fields or acknowledgement rules.

7. Reconcile user balances separately from merchant USDT settlement

Successful user top-up means the balance in the merchant's system was credited correctly. Completed merchant settlement means the associated funds were settled to the merchant as agreed. These are neither the same account balance nor the same state.

After channel collection, T0 real-time USDT settlement is available under the parties' agreement; the network, address, conversion and fees are confirmed separately. Pending settlement must not turn a paid user order into a failed one, and crediting a user does not mean the merchant wallet has received USDT. See complete merchant settlement workflow。

8. Frequently asked questions and launch acceptance

Can a top-up complete after the user closes the page?

Processing can continue from server-side results without the user returning to the page. The merchant must receive notifications correctly and implement query recovery.

Will duplicate callbacks credit the balance twice?

With unique top-up ledger entries and atomic transactions implemented correctly, the same payment is credited only once. Disabling a page button alone does not prevent concurrent duplicate accounting.

How do I start integrating 稳付pay?

Contact the technical team with your website or app, top-up rules and payment needs. Confirm channels and merchant configuration, then follow the developer documentation for integration testing.

Before launch, test at least normal top-ups, duplicate notifications, simultaneous notifications and queries, rollback on database failure, closing the page and late payments. For every case, check the order, payment record, balance ledger entry and final balance to ensure accurate amounts credited only once.

References

Official references clarify payment notifications and QR payment terminology. 稳付pay API fields, signatures and notification acknowledgements follow this site's developer documentation and the configuration enabled for your account.

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 ↗