Alipay Open Platform Integration: App Types, RSA2 Signing, and Async Notifications

Alipay Open Platform Integration: App Types, RSA2 Signing, and Async Notifications

Alipay's documentation is thorough, yet new integrations still stall on three things: the wrong app type blocking product activation, a misunderstood key model causing endless verification failures, and incorrect async notification handling leaving order states inconsistent. None of it is difficult, but the order and the concepts have to be settled first.

For onboarding and qualifications, see the guide to adding Alipay and WeChat Pay to a website. For product capabilities and fee structure, see Alipay. This article covers only the span from first line of code to first settled payment.

1. Choose the App Type First

Creating an app on the Alipay Open Platform requires a type, and that type decides which products can be attached:

Choosing wrongly means recreating the app and re-signing contracts, discarding all prior configuration. There is only one criterion: where the user completes payment, whether a browser, an app, or a mini program.

2. Keys: Configuring the Public Key Model

Alipay offers two key models, and the public key model is both dominant and easiest to reason about. Four steps:

1. Generate an RSA2 key pair locally with the official tool, preferably 2048-bit, keeping the private key on your own server.
2. Upload your application public key to the open platform, which returns an Alipay public key.
3. Configure code with the application private key you generated plus the Alipay public key from the platform.
4. Select RSA2 as the signing method, never RSA.

The point that trips people up: sign with your application private key and verify with the Alipay public key. Many teams use the application public key for verification and every callback fails. The platform involves two distinct public keys, the application public key you upload and the Alipay public key the platform issues, and their purposes do not overlap.

The certificate model, with application public key certificate, Alipay public key certificate and Alipay root certificate, is more capable but costs more to maintain. Small and mid-sized teams are fine with the public key model unless reconciliation or advanced interfaces require certificates.

3. Signing and Requests

The rule is to concatenate public and business parameters in lexicographic order, drop empty values and the sign field, sign with SHA256-RSA using the application private key, then URL-encode the result.

Three practical points:

1. Lexicographic concatenation sorts by parameter name in ASCII order, not by appearance order.
2. Empty values must be excluded. Including an empty string in the signature string is the most common cause of verification failure.
3. Do not post-process parameters around signing. Chinese characters in particular must be encoded consistently as UTF-8.

Use the official SDK rather than hand-rolling string concatenation. Once parameters multiply, hand-written signing becomes nearly impossible to debug.

4. Async Notifications: Five Mandatory Steps

Alipay POSTs payment results to the configured notify_url. The correct order is:

1. Receive parameters and verify the RSA2 signature with the Alipay public key.
2. Confirm app_id matches this application and seller_id is your own collecting account.
3. Confirm out_trade_no exists and the amount matches the local order.
4. Inspect trade_status: treat payment as successful only for TRADE_SUCCESS or TRADE_FINISHED.
5. After business processing completes, output the plain text success.

Step five is the one most often missed. Alipay decides whether notification succeeded based on returning success, so returning an HTML page or an empty response causes scheduled retries. It may look fine initially, then flood once your response body changes. Equally important, never return success before processing, since the record must be persisted first.

Distinguish the two statuses. TRADE_SUCCESS means the trade succeeded and is refundable; TRADE_FINISHED means the trade is closed and no longer refundable. Both count as money received, but refund logic applies only to the former.

5. Scope of the Four Payment Products

Selection logic matches WeChat Pay: decide by the user's environment. Note that QR payment returns a code string that you must render as an image; do not expect the endpoint to return a picture.

6. Query, Close, and Refund

Three auxiliary endpoints matter more for correctness than the payment endpoints:

• Query (alipay.trade.query) confirms state actively. The synchronous redirect result is not trustworthy. If no async notification arrives and the user claims payment, this endpoint is the only reliable arbiter.
• Close (alipay.trade.close) cancels unpaid orders, preventing a user from later completing payment on an old page and creating a duplicate charge. Orders should be closed actively once they expire.
• Refund (alipay.trade.refund) supports partial refunds, and an order can be refunded several times as long as the cumulative total does not exceed the order amount. Refunds are asynchronous and require their own notification or active query.

An often ignored detail: a race exists between closing an order and the user paying. If payment completes while the close request is in flight, the close may fail even though funds arrived. The correct response is to query immediately after a failed close and reconcile against the actual channel state.

7. Common Error Reference

• Signature verification failed: nine times out of ten the wrong public key is used, application versus Alipay, or empty fields were included in the signed string.
• Application not live or no permission: the app is not published, or the product was never contracted.
• app_id mismatch: the configuration file points at another application.
• Duplicate out_trade_no: the merchant order number was reused, but it must be globally unique.
• Notifications keep repeating: the endpoint never returns success, or a framework wraps the response in JSON.

8. Launch Checklist

The app is published and products contracted; private keys never enter the repository and come from environment variables or a secret manager; the notification endpoint requires no login, is publicly reachable, and returns plain text success; amounts are validated in yuan with two decimals; order numbers are globally unique and within length limits; query, close and refund are all implemented; logs are masked and retain raw notification payloads for troubleshooting.

For the general payment sequence, see payment transaction flow basics. For sandbox and integration testing, see payment gateway sandbox testing. The WeChat Pay counterpart appears in WeChat Pay APIv3 integration in practice, and reconciliation in the reconciliation and bill download handbook. More options are collected under the Payment category.

Source: 16IDC original. Product capabilities, pricing and eligibility requirements follow opendocs.alipay.com and related official documentation and contract terms.