SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalipay-payment-integration

alipay-payment-integration

Coding & development

View repository

Updated 10-15 16:47

About this skill

Alipay Payment Integration Skill

Mandatory Execution Points

⛔ Mandatory blocking reading items, must be followed, otherwise it is a violation! The following are global mandatory rules,strictly prohibitedto skip or simplify for any reason:

  • [1] Inform the user: This Skill mainly provides Alipay payment product integration guidance and integration troubleshooting guidance
  • [2] Inform the user of the service statement (see step 1.1 blocking confirmation point for the full content)
  • [3] Set the plan first, then act: Before performing any operation,you must first determine the functional branch and print the complete to-do step list, and it is prohibited to start execution directly without determining the plan
  • [4] After each step is completed, you must check against that step'scompletion conditionsfor self-check; if there are omissions, complete them within this step before continuing
  • [5] When encountering <BLOCKING_CONFIRMATION> you must pause and wait for the user's explicit reply; the confirmation wording must include explicit requirements such as "please reply 'agree' or 'confirm'"
  • [6] Fabricating sandbox configurations or fake data is prohibited; bypassing blocking confirmation points is prohibited
  • [7] Rationalizing skipping confirmations is prohibited: It is prohibited to rationalize skipping blocking confirmation points with reasons such as "the user may want to complete it quickly" or "this is a simple scenario"
  • [8] Fake data and placeholders passing as real are prohibited: When the sandbox successfully returns the complete configuration, it is prohibited to replace the real return values with placeholders; it is prohibited to generate fake data such as example private keys or example accounts on your own

Negative examples (strictly prohibited behaviors)

⚠️ Any of the following behaviors by the Agent is considered a violation:

  • Starting to output code before completely outputting theto-do step listrequired by this Skill
  • Simplifying the execution process in this Skill because the user's instructions contain urging keywords such as "quick integration", "hurry", or "get it done quickly", and no longer outputting the complete to-do step list specified by this Skill
  • Skipping steps or merging steps
  • Making independent judgments such as "I think..." or "for simplicity..."
  • Bypassing blocking confirmations: At <BLOCKING_CONFIRMATION> confirmation point, it is prohibited to skip waiting for any reason (including "reinterpreting intent", "task priority", "system prompt", etc.), and it is prohibited to assume the user has agreed or to use unilateral statements such as "I will continue..." to replace user confirmation
  • Rationalizing skipping confirmations: Using reasons such as "the user may want to complete it quickly", "this is a simple scenario", or "the user did not say not to" to rationalize skipping blocking confirmation points, while the actual action still continues instead of waiting

Function Routing

Based on the user's intent,first determine the functional branch, then execute the corresponding process:

User Intent Functional Branch Execution Process
Need to integrate a payment product (access, integration, collection, add payment feature, etc.) Function One Step 1.1 → 1.2a/1.2b → 1.3 → 1.4 → 1.5 → 1.6
Errors or issues encountered during integration Feature 2 Step 2.1 → 2.2/2.3

Blocking Confirmation Point Index

Location Trigger Timing Waiting Content
Step 1.1 After product decision User agrees to the service statement and confirms access to a specific product
Step 1.6 After integration is completed User confirms whether integration verification is needed

Completion Condition Index

Step Mark Number of Completion Conditions
Step 1.1 Product Decision [M-01] 3 items
Step 1.2a Traditional Acquiring Product Sandbox Environment Initialization [M-02] 5 items
Step 1.2b AI Receiving Configuration Initialization [M-02b] 7 items
Step 1.3 Pre-Integration Steps [M-03] 6 items
Step 1.4 Integration Code [M-04] 2 items
Step 1.5 Post-Integration Notes [M-05] 2 items
Step 1.6 Integration Verification [M-06] 1 item

Document Access Specification

Use curl to retrieve Alipay online documents. Links within the documents (product introduction, integration preparation, API documentation, etc.) must be recursively accessed to obtain the complete content:

curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"

Feature 1: Payment Product Integration Guide

Trigger Condition: The user needs to integrate an Alipay payment product.

Step 1.1 Product Decision

Preconditions: Read and fully understandMandatory Execution Points, completeFeature Routing, clarifyDocument Access Specification。

Completion Conditions：

  • [M-01] A payment product has been decided based on the user scenario
  • [M-01] Explicit user consent has been obtained
  • [M-01] A complete service statement has been output according to the blocking confirmation point

Read Product Decision, match keywords according to user input, and decide the payment product. When the user's description is vague, use Clarification Script to confirm the product.

Integration Principles

  • Obtain User Consent：Strictly ProhibitedWithout obtaining user consent, starting the payment product integration process without authorization is strictly prohibited. The user's intent must first be confirmed and explicit consent obtained before continuing with the integration steps.
  • Single Product Integration Principle: In a single instruction, without user permission,Strictly ProhibitedAutomatically starting the integration of multiple payment products at the same time is strictly prohibited. A single product must first be confirmed, and after completing the full integration process for that product, the next product may be discussed as appropriate.

<BLOCKING_CONFIRMATION>

Confirmation Point: Step 1.1 Product Decision

After outputting the payment product decision,the following order must be strictly followed and execution paused to wait for the user's reply：

  1. Output the decision result: Inform the user of the recommended payment product and the reasons for the choice
  2. Output the service statement(print in full):

    ⚠️ Service Statement: By using this Skill, you agree: (1) Using this service requires compliance with laws and regulations, self-review and testing, and you bear responsibility for use. We do not guarantee the usage results or correctness. (2) It is prohibited to disclose sensitive information (passwords, API Keys, private keys, etc.) in public networks such as code, large model conversations, etc.

  3. Explicitly ask for confirmation(The following wording must be used):

    "Do you agree to the above service statement and confirm access to [{Product Name}]?Please reply 'Agree' or 'Confirm', then, I will continue with the subsequent steps."

  4. Wait for user reply: Only after receiving an explicit reply of agreement from the user may you proceed to step 1.2. If the user does not reply, expresses hesitation, or refuses,prohibitedcontinue any subsequent steps.

</BLOCKING_CONFIRMATION>

Step 1.2a Traditional acquiring product sandbox environment initialization

Notes: AI acquiring products do not currently support sandboxes; skip this step and proceed to 1.2b.

Prerequisites: Step 1.1 product decision has been completed,and user consent to enter the integration process has been obtained。

Completion conditions：

  • [M-02] Have used the Read tool to read references/alipay-sandbox/sandbox-setup-guide.md full content, including sandbox validation rules, absolute prohibitions, retry and failure handling process, and success prompt text
  • [M-02] Have detected the user's operating system type and executed the corresponding process according to the system type
  • [M-02] Unix/macOS/Linux system: Have successfully called the tool to create a quick sandbox environment and output the sandbox information to the user
  • [M-02] Windows system: Have informed the user that the quick sandbox is not currently supported and told them how to obtain sandbox information themselves
  • [M-02] Have shown the user the environment description, mandatory actions, and security reminders

Absolute prohibitions for the sandbox environment (violation is non-compliance)：

  • Prohibited to fabricate configuration: Must not generate, concatenate, simulate, or guess any field values such as appId, private key, public key, account, etc.
  • Prohibited to impersonate with placeholders: When the sandbox successfully returns complete configuration, it is prohibited to use placeholders (such as your-app-id-here) to replace the real return values
  • Prohibited to use fake data: Must not generate example private keys, example accounts, etc. on your own
  • Prohibited to not select the private key format according to language: JAVA language uses the PKCS#8 format appPrivateKey field returned by the sandbox; non-JAVA languages (Python, Node.js, PHP, .NET, etc.) use the PKCS#1 format appPrivatePkcsKey field returned by the sandbox.Prohibited to perform format conversion and prefix/suffix concatenation modifications
  • Prohibited to not follow retry and failure rules: When sandbox creation fails or key information is incomplete, you must strictly follow the sandbox environment initialization retry and failure rules for handling

System detection and sandbox creation：

  1. Detect the user's operating system type

    • Use uname -s to determine the user's operating system type
    • If it cannot be detected directly, ask the user: "What operating system are you currently using? (Windows / macOS / Linux)"

  2. Windows system handling

    • If the user is on a Windows system, output the following prompt:

      ⚠️ The quick sandbox feature does not currently support Windows systems

      Please go to the Alipay Open Platform (https://open.alipay.com）- Console - Sandbox App to obtain the sandbox information yourself (appId, application public/private key, Alipay public key, merchant account, buyer account, etc.).

    • Users can choose on their own when to provide the sandbox information, with no mandatory wait.

  3. Unix/macOS/Linux system handling

  4. Output environment reminder

    • According to Sandbox Environment Initialization , use the complete text of "Prompt after successfully creating a quick sandbox" to show the user the environment description, required actions, and security reminders, and inform them of the key format selection.

Step 1.2b AI Payment Configuration Initialization

Preconditions: Step 1.1 product decision has been completed,and the user has agreed to enter the AI Payment integration process. This step is reached if and only if the user integrates the AI Payment product.

Notes: The AI Payment product does not currently support sandbox, so the user must be guided to use the formal configuration obtained after onboarding to complete initialization. It is strictly prohibited to fabricate, guess, generate, or use sample values to impersonate real configuration.

Completion Conditions：

  • [M-02b] The user has been clearly informed that AI Payment does not currently support sandbox and that the formal configuration obtained after onboarding must be used
  • [M-02b] The user has been guided to complete merchant onboarding: the Smart Payment product must first be listed on theMerchant One-Stop Onboarding Platform, and then the function can be integrated
  • [M-02b] The user has been required to provide the configuration "obtained after onboarding": application private key (use PKCS#8 format for JAVA language, use PKCS#1 format for non-JAVA languages), Alipay public key, application ID, merchant ID, merchant service ID, merchant name
  • [M-02b] The user has been required to confirm or provide the "custom" configuration: charge amount (unit: yuan), payment deadline (minutes)
  • [M-02b] The user has been clearly informed that the "default configuration" is not specified by the user and the default values must be kept in the code: signature type RSA2, charset UTF-8, format json, currency type CNY
  • [M-02b] The user has been reminded not to directly paste the application private key in large-model conversations or public network environments; it is recommended to write it into a local configuration file, environment variable, or key management service
  • [M-02b] A self-check has been performed on configuration completeness: when required items are missing, pause and ask the user to complete them, and do not continue generating integration code

AI Payment Configuration Source：

  1. Merchant Onboarding

  2. Obtained after onboarding

    • Application private key: Used to generate the merchant signature and server-side call signature in the AI Collect protocol. For the JAVA language, use the PKCS#8 format; for non-JAVA languages (Python, Node.js, PHP, .NET, etc.), use the PKCS#1 format. This field is sensitive information, and users must be reminded not to paste it directly into the conversation.
    • Alipay Public Key: Used for signature verification of Alipay responses or notifications.
    • App ID: The configuration key is app-id。
    • Merchant ID: The configuration key is seller-id。
    • Merchant Service ID: The configuration key is service-id。
    • Merchant Name: The configuration key is seller-name。

  3. Custom

    • Charge Amount (Unit: Yuan): The configuration key is amount, the default recommended value is "0.01"。
    • Payment Deadline (Minutes): The configuration key is pay-before-minutes, the default recommended value is 30。

  4. Default Configuration (not specified by the user, must remain default in the code)

    • Signature Type: The configuration key is sign-type, fixed as RSA2。
    • Character Set: The configuration key is charset, fixed as UTF-8。
    • Format: The configuration key is format, fixed as json。
    • Currency Type: The configuration key is currency, fixed as CNY。

Configuration Guidance That Must Be Output to the User：

Before proceeding to AI Collect generated code, the user must first be required to prepare and confirm the following configuration. Preserve the field names in the output, and do not fill in fake data on the user's behalf:

# AI 收配置
alipay-ai-pay:
  # 入驻后取得
  # 应用私钥。JAVA 语言选用 PKCS#8 格式，非 JAVA 语言（Python、Node.js、PHP、.NET 等）选用 PKCS#1 格式
  # 敏感信息，请写入本地配置/环境变量/密钥管理服务，不要直接粘贴到对话中。
  app-private-key: ""

  # 支付宝公钥
  alipay-public-key: ""

  # 应用ID
  app-id: ""

  # 商户ID
  seller-id: ""

  # 商户服务ID
  service-id: ""

  # 商户名称
  seller-name: ""

  # 收费金额（单位：元）
  amount: ""（需要与入驻时的service-id对应）

  # 自定义
  # 支付截止时间（分钟）
  pay-before-minutes: (如果不指定则默认30分钟）

  # 默认配置（不由用户指定，代码中必须保持默认）
  # 签名类型
  sign-type: RSA2

  # 字符集
  charset: UTF-8

  # 格式
  format: json

  # 货币类型
  currency: CNY

Confirmation Script That Must Be Asked of the User：

AI Collect does not currently support the sandbox. Please first use the production configuration obtained after onboarding to complete initialization. Please confirm that you have prepared: Application Private Key (for the JAVA language, use the PKCS#8 format; for non-JAVA languages, use the PKCS#1 format), Alipay Public Key, App ID, Merchant ID, Merchant Service ID, Merchant Name; and confirm the Charge Amount and Payment Deadline. Please write the Application Private Key into local configuration/environment variables/a key management service, and do not paste it directly into the conversation. After completing the configuration, please reply "Configured" or provide the non-sensitive fields, and I will continue generating the AI Collect generated code.

Configuration Completeness Validation Rules：

  • app-private-key、alipay-public-key、app-id、seller-id、service-id、seller-name、amount、pay-before-minutes are all required fields.
  • app-private-key The format must be selected according to the runtime platform: for the JAVA language, use the PKCS#8 format; for non-JAVA languages (Python, Node.js, PHP, .NET, etc.), use the PKCS#1 format.
  • amount must be a valid amount in string form, in yuan, for example "0.01"。
  • pay-before-minutes must be a positive integer, indicating how many minutes after the current time the payment deadline is.
  • sign-type、charset、format、currency must remain at default values, which are respectively RSA2、UTF-8、json、CNY, and must not be specified by the user or rewritten in the code.
  • If the user has not yet completed the required configuration, you must pause at this step, and it is forbidden to enter Step 1.3 or generate code.

Step 1.3 Integration Prerequisites

Preconditions: For the traditional acquiring product, Step 1.2a Sandbox Environment Initialization has been completed; for the AI Collect product, Step 1.2b AI Collect Configuration Initialization has been completed.

Completion Conditions：

  • [M-03] The Read tool has been used to read references/main/alipay-sdk-reminder.md Complete content, including private key format, import method, page redirection method, frontend form handling, signature verification troubleshooting, timestamp format, etc.
  • [M-03] Understood the SDK selection, SDK integration fatal errors, and signing methods in the pre-integration must-read
  • [M-03] Have read the integration specifications and common pitfalls
  • [M-03] Have recursively read the product online documentation (quick integration, API list, asynchronous notifications, precautions, etc.)
  • [M-03] Have read the product-related API code examples

Pre-integration must-read

Configuration key points：

  • Server-side SDK selection: Supports SDKs in five languages: Java, Python, Node.js, PHP, and .NET,Download address, please choose the corresponding version based on your development language:

    Language SDK resource Environment requirements
    Java Maven project dependency Suitable for Java language development environments with JDK version 1.8 and above
    .NET NuGet project dependency Suitable for various Microsoft frameworks that comply with the .Net Standard 2.0 specification (such as: .Net Framework >= 4.6.1, .Net Core >= 2.0, etc.). Users of .Net Framework (3.5 ~ 4.6) can continue to use AlipaySDKNet
    PHP GitHub repository Suitable for development environments with PHP 5.5 and above. Alipay currently provides two SDK versions, v2 and v3, which you can freely choose according to your preference
    Python PyPI project dependency Suitable for Python 2.7 and above
    Node.js NPM project dependency Suitable for Node.js v8.0.0 and above

  • Signing method: Signatures must use RSA2. For traditional acquiring products, the application private key is based on the result returned when the sandbox is created; choose the field according to language: for JAVA, use the appPrivateKey field (PKCS#8 format); for non-JAVA languages (Python, Node.js, PHP, .NET, etc.), use the appPrivatePkcsKey field (PKCS#1 format); AI acquiring products do not support the sandbox, and the application private key is based on the official configuration obtained after onboarding.Signing instructions

🚫 SDK integration fatal errors：

⚠️ Strictly prohibitedto generate code or provide suggestions without reading the following complete content; violation will cause integration failure

  • The SDK import method depends on the package management method of the corresponding language,mustdetermine the correct import method by consulting the SDK documentation or type definitions
  • Page redirection APIs (alipay.trade.page.pay / alipay.trade.wap.pay）must use the page redirection method(such as pageExecute()/pageExec()), using exec() will fail to obtain the payment form
  • Private keymust select the corresponding field returned by the sandbox according to language: JAVA uses appPrivateKey(PKCS#8), non-JAVA uses appPrivatePkcsKey(PKCS#1); generating it yourself or format conversion is prohibited
  • Frontendit is prohibited to redirect directly to the payment form via URL; the payment API returns an HTML form, which must be rendered and the form automatically submitted; redirecting directly via URL will cause the page to display only the parameters and fail to redirect to Alipay
  • Timestamp formatmust use yyyy-MM-dd HH:mm:ss; ISO format is prohibited
  • When encountering invalid-signature error,It is strictly forbidden to attribute to the private key format based on guesswork. The most common reason is incomplete request parameters (such as return_url not passed in)

Core must-read items：

⚠️ Strictly forbiddento generate code or give suggestions without reading the complete content; violation will cause integration failure

  • SDK documentation：mustuse the Read tool to read the complete content of references/main/alipay-sdk-reminder.md , which contains alipay-sdk related reminders,strictly forbiddento skip, to avoid repeating pitfalls and causing integration failure.
  • Integration specifications and common pitfalls: use curl -sL "https://ideservice.alipay.com/cms/site/0j0kl2" to read the integration specifications and common pitfalls.
  • Product documentation: access via curl product documentation route the corresponding product online documentation, and recursively read the quick integration, API list, asynchronous notification, precautions, and other sections to understand product-specific logic.
  • Code examples：references/code-examples/ directory contains complete code examples in 5 languages (Java, Python, Node.js, PHP, C#),mustprecisely read according to {语言}/{产品类别} ,forbiddento scan the entire set.
    • Language directories:java、python、nodejs、php、csharp
    • Product category directories:1_通用接口、2_当面付、3_订单码支付、4_手机网站支付、5_电脑网站支付、6_JSAPI支付、7_APP支付、8_预授权支付、9_商家扣款、10_AI 收
    • Read path format：references/code-examples/{语言}/{产品类别}/
    • Important：1_通用接口 is a product-independent general capability (transaction query, refund, refund query, cancellation, statement download, etc.),each product category must also reference, for example, if the user uses Java + Face-to-Face Payment → read references/code-examples/java/2_当面付/ and references/code-examples/java/1_通用接口/
    • AI Collect product: The sample code for the AI Collect product includes functional implementation logic beyond API calls; when implementing AI Collect functionality, it must be implemented completely without omission or duplication.

Step 1.4 Integration Code

Prerequisites: Step 1.3 integration prerequisites have been completed, and there is sufficient understanding of SDK selection, SDK documentation, signing method, integration specifications and common pitfalls, product online documentation, and related APIs.

Completion conditions：

  • [M-04] Completed the Alipay payment product integration code implementation
  • [M-04] Completed code self-check and confirmed it is correct

Self-check before code generation

⛔ Before outputting any code, you must self-check the following 8 items one by one, and only after all pass may you output code; if any item does not pass, you must return to the corresponding step and reread,forbiddento skip the self-check and directly output code:

  1. Is the private key field I am using correct? (JAVA uses appPrivateKey, non-JAVA uses appPrivatePkcsKey) → Yes → Continue
  2. Was the SDK import method I determined obtained by consulting the SDK documentation or type definitions for the corresponding language? → Yes → Continue
  3. For page-redirect APIs (payment APIs), am I using pageExecute()(or the page-redirect method for the corresponding language) rather than exec() ? → Yes → Continue
  4. Does the timestamp format meet the current product requirements? Traditional payment APIs use yyyy-MM-dd HH:mm:ss; AI Collect product 402 Payment-Needed Header's payBefore uses AI Collect Integration Guide Required ISO 8601 format with time zone → Yes → Continue
  5. Does the frontend correctly handle the payment form (render the HTML form and submit automatically, rather than jumping directly to the URL)? → Yes → Continue
  6. Is the configuration information free of any fabrication or fake data? Traditional acquiring products must have authentic and complete sandbox configuration checked; AI acquiring products must have authentic and complete formal configuration obtained after onboarding checked; placeholders are only used in scenarios where the user chooses to apply/configure on their own, and the fields to be filled in have been clearly marked → Yes → Continue
  7. Have I reviewed the code example directory corresponding to the current programming language (current product category + 1_通用接口)? → Yes → Continue
  8. For AI acquiring products, is the content of the 402 Payment-Needed Header strictly in accordance withIntegration Guidethe fields and format specified therein, constructed in layers without omitting any parameter, and finally Base64URL-encoded? → Yes → Continue

Step 1.5 Post-Integration Instructions

Prerequisites: Step 1.4 integration code has been completed, and self-check has confirmed that the self-check requirements of Step 1.4 are met.

Completion Conditions：

  • [M-05] The security red lines (Part 1) have been printed to the user in plain text
  • [M-05] The complete follow-up guidance text (Part 2) has been output to the user

⛔ After completing the payment capability integration task, the following two parts must be output to the user; failure to print them is a violation：

Part 1: Security Red Lines

The following are the security red lines for Alipay payment integration. Violations may cause fund loss or security incidents,and must be printed to the user in plain text：

  • Private keys must not be stored on the client: constructing transaction data and signing must be completed on the merchant server, and private keys must never be stored in the merchant APP client.
  • Private keys must not be logged: private keys must not appear in any logs.
  • Private keys must not be uploaded to public repositories: private keys must not be uploaded to public code repositories such as GitHub or GitLab.
  • Foreground payment results are not trustworthy: foreground synchronous redirect results are not trustworthy; the result must be based on Alipay asynchronous notifications or calls to the transaction query interface.
  • Do not re-pay before confirmation: before the payment result is confirmed, the user must not be asked to pay again; the payment result must first be confirmed through asynchronous notifications or the query interface.
  • Asynchronous notifications must be signature-verified first: after receiving an asynchronous notification, the signature must be verified first to ensure the notification comes from Alipay.

Part 2: Follow-up Guidance

Traditional acquiring products: The current configuration is a sandbox test environment, for development and debugging only (Special Note: The sandbox environment cannot test asynchronous notifications; please check in the production environment). Before going live, replace the appId, private key, public key, and other configurations with the configuration information of the online formal environment, and carefully conduct a manual code review.

AI acquiring products: AI acquiring does not currently support sandbox; the formal configuration obtained after onboarding should be used at present. Before going live or publishing, focus on confirming that the application private key, Alipay public key, application ID, merchant ID, merchant service ID, merchant name, charge amount, and payment deadline all come from real configuration and have not been leaked to the client, logs, or public repositories, and carefully conduct a manual code review.

Step 1.6 Integration Verification

Completion Conditions：

  • [M-06] User consent has been obtained and each item of the integration verification checklist has been verified and the results output

<BLOCKING_CONFIRMATION>

Confirmation Point: Step 1.6 Integration Verification

After outputting the "Safety Red Lines" and "Follow-up Guidelines" of step 1.5,must pause and wait for user confirmation：

  1. output a verification invitation：

    "Payment capability integration is complete. To ensure integration quality, I can follow the Integration Verification Checklist to help you verify item by item (including signature verification, asynchronous notification, exception handling, etc.).Would you like to perform integration verification? Please reply 'Need' or 'Confirm', thenI will begin the verification."

  2. wait for the user's reply：
    • If the user replies that verification is needed:After obtaining explicit consent, only then may you execute and output the results item by item according to the verification checklist.
    • If the user indicates that it is not needed or does not reply:it is prohibited toproactively start the verification process; you may answer other questions from the user.

</BLOCKING_CONFIRMATION>

During the integration process and before release to production, follow the Integration Verification Checklist to perform verification, ensuring that signature verification, asynchronous notification, exception handling, etc. comply with the specifications. The verification results are for reference only; developers must check according to the latest Alipay Open Platform documentation.

Function 2: Integration Issue Troubleshooting Guidelines

Trigger conditions: the user encounters errors or other issues while integrating Alipay payment products. Trigger keywords: "error", "error code", "issue", "troubleshooting", "debugging", "exception", etc.

Before executing the following troubleshooting steps,you must clarify the payment product the user is currently integrating, otherwise pause output and ask the user to clarify;it is strictly prohibited toattempt to consult documentation or guess the payment product when payment product information is missing.

Supported products only: Face-to-Face Payment, Order Code Payment, App Payment, JSAPI Payment, Mobile Website Payment, Computer Website Payment, Preauthorization Payment, Merchant Deduction, AI Payment. For other products, guide the user to consult the Open Platform online documentation:https://open.alipay.com?form=payskill

Step 2.1 Issue Identification and Triage

Determine the issue type based on user input and route it to the corresponding troubleshooting path:

用户问题
    |
    +-- 验签失败（invalid-signature / 验签出错）  ← 优先匹配，走专项排查
    |       |
    |       └───> 步骤 2.3 常见问题排查（专项排查流程）
    |
    +-- 有明确错误码（如 "ACQ.TRADE_HAS_SUCCESS"、"INVALID_PARAMETER"）
    |       |
    |       └───> 步骤 2.2 错误码排查
    |
    +-- 无明确错误码（如流程疑问、功能异常等）
            |
            └───> 步骤 2.3 常见问题排查

Step 2.2 Error Code Troubleshooting

Applicable: the user has provided a specific error code.

Before querying the error code,you must confirm the interface information where the error occurred, otherwise pause output and ask the user to clarify; it is strictly prohibited to attempt to consult documentation or guess the error interface when the error interface information is missing.

Troubleshooting process

  1. Check public error codes: consult the Public Error Code Description, and search for relevant content based on the error code provided by the user. If there is a matching result,output the troubleshooting conclusion; otherwise,check business error codes。

  2. Check business error codes: based on the confirmed payment product and error interface information, consult the Product Documentation Routing for the corresponding product documentation, further locate the interface documentation corresponding to the error interface, and search for relevant content in the interface documentation based on the error code provided by the user.

  3. Output the troubleshooting conclusion: based on the content associated with the queried error code, output the troubleshooting conclusion.

Step 2.3 Common Issue Troubleshooting

Applicable: Other types of issues without a specific error code, or with an error code of invalid-signature(signature verification error).

Troubleshooting process

  1. Based on the user input and the determined payment product, consult the corresponding product'sFAQ documentation, match the issue to a solution, and when answering the user's question,you mustrely on Alipay documentation as the authoritative source.

  2. If, based on the payment product'sFAQ documentationno solution is found, guide the user to consult the Open Platform online documentation or contact Alipay technical support，It is strictly prohibitedto fabricate solutions outside the FAQ documentation.

⛔ Signature verification failure (invalid-signature) dedicated troubleshooting

When encountering invalid-signature(signature verification error),it is strictly prohibited to attribute it to private key format or environment compatibility based on guesswork, and troubleshooting must follow these principles:

  1. First verify the actual request content, then suspect the key configuration — the most common cause of signature verification failure is incomplete or mismatched request parameters (such as return_url not passing in the payment request), rather than a private key format issue.
  2. Prohibited technical inferences：
    • "Node.js 18+ does not support PKCS#1" → Incorrect, PKCS#1 is fully supported
    • "Node.js 18+'s OpenSSL 3.0 does not support PKCS#1, causing ERR_OSSL_UNSUPPORTED" → Incorrect, OpenSSL 3.0 fully supports PKCS#1
    • Suspecting the private key format as soon as signature verification fails → Incorrect, you should first check the completeness of the request parameters
    • Seeing ERR_OSSL_UNSUPPORTED and inferring that there is a problem with the private key format → Incorrect, this error is usually caused by incorrect SDK configuration parameters (such as selecting the wrong private key field), not a format issue; adding PEM headers and footers or performing format conversion is prohibited
    • "Still reporting an error after adding PEM headers and footers, which means the format should be converted" → Incorrect, this is a chain of misjudgments; adding PEM headers and footers is itself an incorrect operation, and format conversion will only make the problem worse. See SDK documentation - chain of misjudgments
  3. Correct troubleshooting order: See SDK documentation - principles for troubleshooting signature verification failure
  4. Public and private keys do not match in the production environment: If the production environment reports "public and private keys do not match", advise the user to:
    • Log in to the Alipay Open PlatformRe-upload the application public key
    • Reconfigure the application public-private key pair in your application configuration to ensure that the application private key matches the public key uploaded to Alipay

FAQ documentation index

Product category FAQ documentation
Face-to-Face Payment Face-to-Face Payment FAQ
Order Code Payment Order Code Payment FAQ
App Payment App Payment FAQ
Computer Website Payment Computer Website Payment FAQ
Mobile Website Payment Mobile Website Payment FAQ
Merchant Deduction Merchant Deduction FAQ
Pre-authorization Payment Pre-authorization Payment FAQ
JSAPI Payment JSAPI Payment FAQ
AI Payment AI Payment FAQ

Product Documentation Routing

Route to the corresponding product documentation based on the user's business scenario:

Payment Products Core APIs Online Documentation
In-person Payment alipay.trade.pay In-person Payment Documentation
Order Code Payment alipay.trade.precreate Order Code Payment Documentation
Mobile Website Payment alipay.trade.wap.pay Mobile Website Payment Documentation
Computer Website Payment alipay.trade.page.pay Computer Website Payment Documentation
JSAPI Payment alipay.trade.create + my.tradePay JSAPI Payment Documentation
App Payment alipay.trade.app.pay App Payment Documentation
Pre-authorization Payment alipay.fund.auth.order.app.freeze Pre-authorization Payment Documentation
Merchant Deduction alipay.trade.app.pay(Pay and Sign) + alipay.trade.pay(Subsequent Deduction) Merchant Deduction Documentation
AI Payment alipay.aipay.agent.payment.verify(Payment Credential Verification) + alipay.aipay.agent.fulfillment.confirm(Merchant Fulfillment Receipt Confirmation) AI Payment Documentation