Top-up integration

Alipay top-up integration: website and app payments, callbacks and balance accounting

An Alipay top-up means a user pays through Alipay to fund their account on your website or app. After confirming the payment result, 稳付pay sends an order notification to your server. Your system verifies the signature and order, then credits the correct user's internal balance. The integration must make payment, notification and accounting traceable to one another and ensure that the same payment is never credited twice.

Contents

1. Distinguish user top-ups, payment collection and account bookkeeping

The user funds a balance in the merchant's system rather than the Alipay wallet itself. 稳付pay provides enabled Alipay native collection channels, payment result confirmation and notifications. The merchant manages user accounts, balance ledger entries, spending records and after-sales rules.

The top-up page should explain how credit may be used, its validity, bonus amounts and refund conditions. Record actual payments and bonuses separately rather than inferring payment amounts from the total credited balance. Spending, refunds and manual adjustments each need separate ledger entries; do not alter accounts by deleting original top-up records. This service does not imply that Alipay withdrawals or USDT exchange are available. The standalone payout API is not currently open.

2. How an Alipay top-up completes

  1. User submits a top-upThe backend binds the user, determines the amount and saves a unique top-up order.
  2. Create an Alipay paymentCall an enabled channel and display the actual payment information returned.
  3. Platform verifies the collection result稳付pay associates the original order and confirms successful payment.
  4. Send a server-side notificationSend the standard callback to the merchant's configured notifyUrl.
  5. Merchant verifies the signature and orderCheck the signature, merchant, order, amount, currency and successful state.
  6. Credit the balance atomicallySave the payment, unique top-up ledger entry and balance update in one transaction.
Successful payment and crediting the internal balance are consecutive but separate facts. The merchant must complete the accounting reliably.

3. Fix the user, amount and channel configuration

Before order creation, save the user ID, merchant order number, amount, currency and a snapshot of the top-up rules. These are merchant business records, not new API parameters. Calculate the payable amount from trusted backend data. Do not accept a browser-modified price or change the credited user when the callback arrives.

Follow the collection order creation and query documentation to supply parameters including mchId, wayCode, outTradeNo, amount, notifyUrl, reqTime and sign. amount is in fen: 1000 represents 10.00 yuan. reqTime uses the current millisecond timestamp. The Alipay aggregate code is 80001 and is available only when the merchant is authorized and the channel is actually enabled.

Alipay native is the business name of a current channel on this site. The technical team confirms payment pages, device requirements and integration interactions for the configured channel. There is no promise that every channel supports every app, H5 or QR payment scenario. Display only an actual, valid payment entry returned by the service; do not construct cashier URLs yourself.

On the actual Alipay payment page, users should check the displayed recipient and amount due. If either differs from the current top-up order, pause payment and contact the merchant for verification rather than changing the amount and asking the backend to match it afterward. Merchant payment instructions should explain order associations and query access so users can review their payment later.

4. Verify callbacks using the 稳付pay protocol

Follow the signing rules and callback documentation to process sign in the Body. Prefer CALLBACK_SECRET for callbacks; use MD5_SECRET only if no separate callback key is configured. Sort and concatenate the actual nonempty fields, then calculate lowercase MD5. Preserve original strings such as 00 and 10.00 instead of converting them to 0 and 10 before verification. Keep keys only on the server.

After signature verification, check merchant ownership, business type, the original order, platform order, amount in fen and currency, and confirm the successful state. Do not automatically credit unknown orders or amount mismatches; retain an exception and ask technical staff to investigate. A successful frontend redirect or a user clicking Paid may only trigger a progress query to your own backend.

This site's aggregate interface differs from Alipay's official direct integration protocol. Alipay's official SDK RSA2 signing implementation cannot replace the MD5 rules used here. Likewise, a success acknowledgement example from elsewhere does not define this article's workflow. For standard 稳付pay callbacks, return HTTP 200 with plain-text OK after reliably saving the result.

5. Protect account balances with unique ledger entries

Give top-up ledger entries a database unique constraint, such as merchant plus top-up order. Commit the order, payment record, top-up ledger entry and balance change in one transaction. Do not credit the balance first and separately mark it processed afterward. Disabling a page button or checking for existence before insertion cannot stop concurrent notifications.

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

This is merchant accounting pseudocode, not a new API. Roll back on failure instead of acknowledging success early. After verification, duplicate notifications already processed reliably may return OK. A successful query also calls the same accounting function, so callbacks, retries and manual recovery share one duplicate-prevention boundary.

6. Query the original order for timeouts and duplicate notifications

SituationHandling
Order creation request times outKeep the original order number for queries instead of immediately creating another top-up under a new number.
Payment completed but balance did not changeCheck the payment, notification processing and top-up ledger entry. Do not credit funds directly from a screenshot.
Duplicate notifications or concurrent queriesUse the same accounting transaction protected by the unique constraint.
A valid payment arrives for an expired orderPreserve the payment fact and credit or refund under the agreed rules; do not ignore it.

The transaction in a user's Alipay statement, platformOrderNo returned by 稳付pay and outTradeNo generated by the merchant identify records in different systems. Do not assume all three are the same. The backend must retain their association. Support should locate the original merchant order before checking payment evidence, rather than crediting funds based only on a transaction number suffix, nickname or matching amount.

稳付pay sends at most 3 notification 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 necessary. Confirm query response amount units during onboarding before converting and comparing; do not directly treat the value as the order request amount in fen. Alipay's official SDK also provides transaction query requests; this reference illustrates active verification only. Actual calls still use the 稳付pay collection query endpoint.

7. Reconcile user top-ups separately from merchant USDT settlement

A user balance increase means the merchant's account system has completed accounting. Completed merchant USDT settlement means the associated funds were settled to the receiving address as agreed. These two record layers must not share a single completed state.

After Alipay 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 the user does not mean the merchant wallet has received USDT. See complete merchant settlement workflow to link each user order, payment record, settlement statement and on-chain record.

8. Frequently asked questions and pre-launch acceptance

Can a top-up succeed after the user closes the payment page?

The backend can continue processing valid notifications or query results without the user returning to the page. The merchant must implement reliable accounting and recovery.

Can Alipay and existing WeChat top-ups share an account balance?

They may share the merchant's balance ledger, but orders retain their payment method and original channel. Each payment must produce only one valid top-up ledger entry.

Can I integrate by changing the URL in an existing Alipay plugin?

First compare fields, signing, callbacks and queries. Replacing the gateway in an official direct integration plugin does not complete an aggregate adapter. Ask the technical team to help with integration testing.

Before launch, test normal top-ups, invalid signatures, amount mismatches, duplicate notifications, simultaneous notifications and queries, database rollback and late payments. For every test, check the order, unique ledger entry and final balance to confirm the correct amount is credited only once. For WeChat integration, see WeChat top-ups and account crediting。

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 ↗