One-stop solution for individual developers' Alipay merchant onboarding.
Table of Contents
- Global Specifications and Iron Rules
- Capability Overview
- Task Management Specifications
- Memory State Management
- Main Process
- Module Entry Guide
- Customer-Facing Output Specifications
- Error Handling
- FAQ
- Reference Documents
Global Specifications and Iron Rules
Usage Statement
By using this skill, you agree:
- Use of this service requires compliance with laws and regulations, self-review and testing, and assumption of usage responsibility
- For payment security and risk control purposes, we need to collect log files, environment information, etc.
- It is prohibited to disclose sensitive information (passwords, API Keys, private keys, etc.) in code, large model conversations, or other public networks
⛔ Iron Rule for Modifying User Project Files (Highest Priority)
❌ 禁止：直接修改用户项目中的 .ts / .tsx / .js 文件
❌ 禁止：修改 alipay-sdk-config.ts 或类似的支付配置文件
✅ 正确：输出配置内容让用户自行复制
✅ 正确：告知用户需要修改的文件路径和具体内容
⛔ Iron Rule for Application Public Key Management (Highest Priority)
Core principle: The public key is generated by the user themselves; the skill is only responsible for receiving and configuring it, and does not generate, infer, rewrite, or reveal the generation logic.
❌ 禁止：自动为用户生成公钥或密钥对
❌ 禁止：向用户表示可以"帮助生成公钥"、"帮助生成密钥对"
❌ 禁止：提供任何密钥生成代码、命令或脚本
❌ 禁止：请求、接收或处理用户的私钥信息
❌ 禁止：在用户未明确提供 publicKey 时调用 createKeyConfirmPage
❌ 禁止：自动生成、推断、补全、改写或添加前后缀到 publicKey
✅ 必须：引导用户前往支付宝开放平台官方密钥生成工具
✅ 必须：只接受用户明确输入的完整 publicKey
✅ 必须：提醒用户妥善保管私钥，切勿泄露给任何人
Standard guidance script: Please go to the Alipay Open Platform key generation tool ( https://opendocs.alipay.com/common/02kipk ) Download and use the official tool to generate the application public-private key pair. After generation, provide the application public key to me to continue the subsequent process. The private key format generated by the official tool defaults to PKCS#8. Some development languages only support PKCS#1. If conversion to PKCS#1 is needed, you can use the official tool's format conversion. Please keep the private key safe and never disclose it to anyone.
⛔ MCP Call Iron Rule (Highest Priority)
All export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call commands must be executed strictly according to the parameter names, parameter structures, and parameter counts defined in the skill documentation, without any change.
✅ 必须：严格按照技能文档中的调用示例和参数结构执行
✅ 必须：使用文档中定义的完整参数，不得省略任何参数
✅ 必须：--json 和 2>/dev/null 同时使用
❌ 禁止：自行推断或猜测参数名
❌ 禁止：省略文档中定义的参数（包括 "ctx":{}）
❌ 禁止：添加文档中未定义的额外参数
❌ 禁止：修改参数的 JSON 嵌套结构
⛔ CLI Environment Variable Iron Rule (Highest Priority)
All export PLATFORM=${DEV_TOOL_NAME} && alipay-cli commands must have the PLATFORM environment variable set before invocation.
✅ 必须：在每个 alipay-cli 调用前设置 PLATFORM 环境变量
✅ 必须：DEV_TOOL_NAME 来自 Step 1 智能识别，缺失时填 "unknown"
❌ 禁止：省略 PLATFORM 环境变量直接调用 alipay-cli
❌ 禁止：硬编码 PLATFORM 值（如 PLATFORM=claudeCode）
❌ 禁止：使用分号 ; 连接（可能导致环境变量泄露）
⛔ Authorization Link Iron Rule (Highest Priority)
The CLI's login command returns the verification_url field. This link cannot be used for authorization and is prohibited from being exposed to the user!
❌ 禁止透出：https://opengw.alipay.com/oauth/device（此链接无法授权）
✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx&platform=xxx
⛔ Iron Rule for Handling createKeyConfirmPage Return (Highest Priority)
In the returned result, it is prohibited to display the QR code link and the alipays:// protocol link; only display the confirmPageUrl Markdown link.
❌ 禁止展示：二维码提示、alipays:// 协议链接
✅ 必须：将 confirmPageUrl 以 Markdown 链接格式输出
✅ 必须：等待用户确认后再继续后续步骤
⛔ Iron Rule for Handling Insufficient Authorization Scope (Highest Priority)
When insufficient authorization scope is detected, you must execute logout to log out, and then re-authorize.
❌ 禁止：检测到授权范围不满足后继续执行后续操作
❌ 禁止：不执行 logout 直接重新登录
✅ 必须：检测到后先 logout 再重新授权
✅ 必须：重新授权时使用正确的 scope（根据当前 salesCode 确定）
For the detailed handling process, see
scripts/handle_scope_mismatch.sh
Capability Overview
| Capability | Description |
|---|---|
| Product Recommendation | Recommend suitable contracted products based on the user's business scenario (Computer Website Payment/AI Collection) |
| MCC Category Selection | Guide users to select business categories and provide intelligent recommendations |
| Login Authorization | alipay-cli OAuth authorization to obtain user identity and permissions |
| Qualification Information Collection | Collect website screenshots or service registration information based on product type |
| Product Signing | Submit signing application to enable payment capabilities |
| Application Publishing | Query existing applications, reuse/create applications, set public key, submit for review |
| Service Marketplace Registration | Listing of AI Collection products on the service marketplace |
Task Management Specifications
The onboarding process must use TaskCreate/TaskUpdate/TaskList for task management to ensure the process is traceable and resumable.
Task-Step Mapping Table (Mandatory Compliance)
| Task Number | Task Name | Corresponding Step | Execution Content |
|---|---|---|---|
| Task 1 | Environment Check | Step 1 | Check alipay-cli installation status and runtime environment |
| Task 2 | Solution Planning | Step 2 | Recommend products and business categories based on user business |
| Task 3 | Login Authorization | Step 3 | Alipay OAuth authorization login |
| Task 4 | Data Collection | Step 4 | Collect website screenshots (only when Computer Website Payment is not signed) |
| Task 5 | Onboarding Advancement | Step 5 | Signing, service registration, application publishing |
| Task 6 | Process End | Step 6 | Output onboarding result |
Task Creation Iron Rules (Highest Priority)
All 6 tasks must be created at once in strict order, no disorder, no omissions:
TaskCreate({ subject: "环境检查", description: "检查 alipay-cli 安装状态和运行环境" })
TaskCreate({ subject: "方案规划", description: "根据用户业务推荐产品和经营类目" })
TaskCreate({ subject: "登录授权", description: "支付宝 OAuth 授权登录" })
TaskCreate({ subject: "资料采集", description: "收集网站截图（仅电脑网站支付未签约时）" })
TaskCreate({ subject: "入驻推进", description: "签约、服务注册、应用发布" })
TaskCreate({ subject: "流程结束", description: "输出入驻结果" })
Task Skipping Rules
| Condition | Skipped Task | Handling Method |
|---|---|---|
| AI Collection product | Task 4: Data Collection | Directly mark as completed, output "AI Collection requires no data collection" |
| Already signed status | Task 4: Data Collection | Directly mark as completed, output "Already signed, skipping data collection" |
| Existing live application | Part of Task 5 content | Only execute service registration or application publishing, skip duplicate steps |
In-Memory State Management
State data is kept in the conversation context, not persisted to files. Automatically cleaned up after the process ends.
{
"productName": "电脑网站支付|AI收",
"salesCode": "I1080300001000041203|I1080300001000160457",
"scope": "app:all,fast_instant_trade_pay:write|app:all,machine_pay:write,agmnt:write",
"mccCode": "Axxxx_Bxxxx",
"mccName": "一级类目 > 二级类目",
"collect_information": {
"pc_home_page_image": "fileKey（仅电脑网站支付）",
"pc_shop_page_image": "fileKey（仅电脑网站支付）",
"pc_payment_image": "fileKey（仅电脑网站支付）"
}
}
Prohibited storage: deviceCode / browserUrl / verificationCode / ar_sign_data / service_market_data / appId / authToken, etc.
Main Process
Process Overview
Step 1: 环境检查 → Step 2: 方案规划 → Step 3: 登录授权
→ Step 3.1: 签约状态查询（子操作）→ 判断后续流程
→ Step 4: 资料采集（条件执行）
→ Step 5: 入驻推进（签约 + 服务注册 + 应用发布）
→ Step 6: 流程结束
Step 1: Environment Check
1.1 CLI Installation Check
if ! export PLATFORM=${DEV_TOOL_NAME} && alipay-cli version &>/dev/null; then
echo "🔄 正在安装 alipay-cli..."
curl -fsSL https://opengw.alipay.com/alipaycli/install | bash
fi
1.2 Task Creation (must be completed before executing any Step)
Create all 6 tasks in order (see Task Management Specifications), with no operations performed in between.
1.3 Intelligent Identification of AI Programming Tools
Execute
scripts/detect_dev_tool.sh, write the return value toDEV_TOOL_NAME. If missing, fill in "unknown". Only output "Environment is ready, you can continue the process.", do not disclose detection details.
1.4 In-Memory State Initialization
Initialize conversation context variables: productName, salesCode, scope, mccCode, mccName, collect_information
Step 2: Solution Planning
Core principle: Recommend directly + adjust only if not accepted
- Based on the user's descriptiondirectlyrecommend products and business categories, without asking or hesitating
- User confirms → proceed to Step 3; user does not accept → provide alternatives in the same category (up to 3)
Product Matching Rules
| Scenario Keywords | Recommended Product | salesCode | scope |
|---|---|---|---|
| website, web page, PC, computer, e-commerce, mall | Computer Website Payment | I1080300001000041203 | app:all,fast_instant_trade_pay:write |
| AI, agent, large model, Agent, MCP | AI Payment | I1080300001000160457 | app:all,machine_pay:write,agmnt:write |
| No clear scenario characteristics | Computer Website Payment (default) | I1080300001000041203 | app:all,fast_instant_trade_pay:write |
MCC Matching
Read
references/mcc-reference.mdfor semantic matching.LLM is prohibited from generating mccCode on its own.
Process After User Confirmation
After the user confirms the solution → directly proceed to login authorization and output the authorization information, no further confirmation is needed.
Step 3: Login Authorization
See
references/authorization.md
Key Process
- whoami checks login status (does not interrupt the process when expired; handled uniformly in Step 3)
- Execute
export PLATFORM=${DEV_TOOL_NAME} && alipay-cli login --non-interactive --scope "$SCOPE" --json 2>&1 - Parse device_code → construct authorization link
https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx&platform=xxx - Output authorization information (product type, business category, confirmation code, link) → wait for user confirmation
- Execute after user confirmation
export PLATFORM=${DEV_TOOL_NAME} && alipay-cli login --complete --json 2>&1
Scope Mapping
| Product | scope |
|---|---|
| Computer Website Payment | app:all,fast_instant_trade_pay:write |
| AI Payment | app:all,machine_pay:write,agmnt:write |
Authorization Information Display Specification (Highest Priority)
Must display 4 fixed items of information + authorization link (Markdown format); conditional hiding is prohibited:
- Product type 2. Business category (mccName + mccCode) 3. Confirmation code 4. Authorization link validity period + link
Step 3.1: Post-Authorization Processing (Login Authorization Sub-process)
Signing Status Query
export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call ar-query.queryArInfosBySalesProd \
-d '{"request":{"salesProductCodes":["<salesCode>"]},"ctx":{}}' --json 2>/dev/null
Signing Status Determination and Branching
| Status | Product Type | Subsequent Process |
|---|---|---|
| NOT_SIGNED | Computer Website Payment | Step 4 Material Collection (3 screenshots) → Step 5 |
| NOT_SIGNED | AI Payment | Directly Step 5(signing + service registration + application publishing) |
| SIGNED | Computer Website Payment | Directly Step 5(application publishing only) |
| SIGNED | AI Payment | Directly Step 5(service registration + application publishing) |
For detailed determination logic and scripts, see
references/product-sign.mdandscripts/query_sign_status.sh
Step 4: Material Collection
⚠️ Only executed for the "Computer Website Payment" product and when not yet signed; AI Payment skips this step.
📋 电脑网站支付需要 3 张网站截图：
1. 首页截图 2. 商品页截图 3. 支付页截图
请上传截图后继续。
For upload and parsing scripts, see
scripts/upload_screenshots.sh
# 上传截图获取 fileKey
export PLATFORM=${DEV_TOOL_NAME} && alipay-cli file upload "$FILE_PATH" -s payMerchantcodeSkill --json 2>/dev/null
Step 5: Onboarding Advancement
⚠️ Signing, service registration, and application publishing are executed serially.
| Step | Module | Applicable Products | See |
|---|---|---|---|
| 5.1 | Product Signing | All products | references/product-sign.md |
| 5.2 | Service Marketplace Registration | AI Collect Only | references/service-registration.md |
| 5.3 | Application Release | All Products | references/app-release.md |
Step 6: End of Process
Output format details are inCustomer-Facing Output Specification - End of Process Output Specification
Use TaskUpdate to mark all tasks as completed.
⛔ Iron Rule of Mandatory Module Reading (Highest Priority)
Before executing any module, you must first read the corresponding references document to obtain the complete parameters and process. It is forbidden to execute from memory!
✅ 必须：执行签约相关操作前 → 先读取 references/product-sign.md
✅ 必须：执行应用发布相关操作前 → 先读取 references/app-release.md
✅ 必须：执行服务市场注册相关操作前 → 先读取 references/service-registration.md
✅ 必须：执行登录授权相关操作前 → 先读取 references/authorization.md
❌ 禁止：不读文档直接调用任何 MCP 方法
❌ 禁止：凭记忆猜测或推断 MCP 方法名、参数名、参数结构
❌ 禁止：自行编造文档中不存在的 MCP 方法（如 deleteService、updateApplication 等）
❌ 禁止：将签约模块的 ctx 参数习惯带入应用发布模块
❌ 禁止：将应用发布模块的无 ctx 习惯带入签约模块
Module Entry Guide
Signing Module → references/product-sign.md
⚠️ This document must be read before executing signing
- Features: Signing status query + Signing application submission
- MCP: ar-sign.apply / ar-query.queryArInfosBySalesProd (⚠️ ctx required)
- Signing JSON structure (Computer Website Payment includes webAppDTO+screenshot / AI Collect has no webAppDTO)
- Key variables: bizRequestNo (generate a new UUID each time), mccCode, channelCode, orderType
- Signing output specification (rate disclaimer)
Application Release Module → references/app-release.md
⚠️ This document must be read before executing application release
- Features: Query existing applications → Reuse/Create → Set public key → Submit for review
- MCP: apprelease.* (7 methods) (⚠️ ctx not required, parameter structure is completely different from the signing module)
- ⛔ Iron Rules for Application MCP Calls (wrapped in request, no ctx, appTypes uses an array)
- Mandatory principle for application reuse (only ON_LINE status may be reused)
- createKeyConfirmPage return handling specification (only display confirmPageUrl)
Service Marketplace Registration Module → references/service-registration.md
⚠️ This document must be read before executing service registration
- Features: AI Collect product service listing (query before create)
- MCP: Only 2 methods → a2a-pay-service.discoverBazaarServicesForMcp / saveBazaarServiceForMcp
- 5-step process: Query → Judge → User decision → Submit → Handle result
- ⛔ Prohibited: Using methods not defined in the document (such as deleteService, updateService)
- Input parameter validation rules + service count ≤20 limit + all fields must be passed for modification
MCC Recommendation Module → references/mcc-reference.md
- MCC category reference table, used for semantic matching to recommend business categories
- ⛔ The LLM is prohibited from generating mccCode on its own; it must be precisely matched from the document
CLI Command Specification → references/cli-commands.md
- Call formats and parameter specifications for all alipay-cli commands
- Detailed instructions for login/authorization/file upload/MCP calls
MCP Method Declarations → references/mcp-methods.md
- Parameter structures and call examples for all MCP methods
- ⛔ Fictitious MCP method calls are strictly prohibited
Login Authorization → references/authorization.md
- Complete process for login status check, authorization link generation, reauthorization, and permission check
- ⛔ Iron Rule of Three Parameters for Reauthorization (deviceCode, productCode, mccCode are all indispensable)
Error Handling → references/error-handling.md
- Error type identification priority + Unified error handling template
- Handling of MCP authentication errors, service errors, authorization mismatches, and backend business errors
Customer-Facing Output Specification
1. Solution Planning Output Specification
让我先帮您规划方案，然后逐步完成入驻流程。
---
📋 根据您的[用户业务描述]，我为您推荐以下方案：
| 项目 | 信息 |
|------|------|
| 产品类型 | [产品名称] |
| 经营类目 | [一级类目] > [二级类目] ([mccCode]) |
请确认方案是否合适？确认后将继续下一步。
Output for rejected adjustments:
📋 了解，为您推荐[一级类目]类目下的其他选项：
| 序号 | 经营类目 | 适用场景 |
|------|----------|----------|
| 1 | [一级类目] > [二级类目1] | [适用场景1] |
| 2 | [一级类目] > [二级类目2] | [适用场景2] |
请选择序号，或继续描述您的经营场景。
2. Service List Output Specification
| No. | Service ID | Service Name | Description | Price | Status | Service Address |
3. Signing Information Output Specification (including rate disclaimer)
When the signing information includes rates,a disclaimer must be attached：
📋 签约信息：
• 签约状态：[状态]
• 费率：[费率值]
> 由于支付宝可能会有阶段性的优惠活动，实际费率可能低于该页面费率，具体以相应费用账单为准。
4. Process End Output Specification
Computer Website Payment:
🎉 支付宝商家入驻流程结束！
| 模块 | 项目 | 信息 |
|------|------|------|
| 📦 产品信息 | 产品类型 | [产品名称] |
| 📦 产品信息 | 经营类目 | [类目名称] |
| 📋 签约信息 | 签约状态 | [状态] |
| 📋 签约信息 | 费率 | [费率值]（如有） |
| 📱 应用信息 | 应用ID | [appId] |
| 📱 应用信息 | 应用状态 | [状态] |
> 由于支付宝可能会有阶段性的优惠活动，实际费率可能低于该页面费率，具体以相应费用账单为准。
AI Collection Product (including Service Market information): On the basis of the above table, add a 🔧Service Information row (Service ID, Service Name, Service Description, Service Status, Service Address).
Error Handling
| Error Type | Identifying Keyword | Handling Method |
|---|---|---|
| Authentication Error | HTTP 401, Authorization is empty | logout → reauthorize |
| Service Error | MCP call failed (non-401) | Prompt to check the network and retry |
| Authorization Information Mismatch | mccCode/salesProductCodes is not auth, scope is not auth | logout → reauthorize |
| Signing Error | errorCode, errorMessage | Display the error and guide the user to correct it |
Unified Error Detection Template:
if echo "$RESULT" | grep -qiE "HTTP 401|Authorization is empty|mccCode.*is not auth|salesProductCodes.*is not auth|scope.*is not auth|授权信息不匹配"; then
# → 执行 scripts/handle_scope_mismatch.sh
fi
For detailed error handling, see
references/error-handling.md
FAQ
Product-related
Q: Can Computer Website Payment be activated if the website is not yet online? A: Yes, just upload a screenshot of the website. Q: Can an individual account activate Computer Website Payment? A: Yes, a business license with a matching name is required. Q: What is the AI Collection product? A: AI Collection is an acquiring product that enables agent-to-machine payments through Alipay. Q: How can an individual increase the collection limit after activating AI Collection? A: An individual industrial and commercial household business license with a matching legal representative is required.
Signing-related
Q: What should I do if "the operation behavior poses a risk" is prompted during signing? A: The system has detected an abnormality in the account. Please try again later. Q: How do I close a product? A: Log in to b.alipay.com → Product Center → find the product → close the product.
For the complete FAQ, see
references/faq.md
Referenced Documents
| Document | Content |
|---|---|
references/product-sign.md |
Complete signing module process, JSON structure, status determination |
references/app-release.md |
Complete application publishing process, MCP call rules, reuse specifications |
references/service-registration.md |
Service Market registration process, input parameter validation, query before creation |
references/authorization.md |
Complete login authorization process, scope validation, reauthorization |
references/flow.md |
Detailed execution flowchart and branch logic |
references/cli-commands.md |
Detailed CLI command description |
references/mcp-methods.md |
MCP method declarations, parameter structures, method routing |
references/products.md |
Product configuration, MCC format, information collection requirements |
references/error-handling.md |
Detailed error handling description |
references/faq.md |
Frequently asked questions |
references/mcc-reference.md |
MCC category reference table |
references/state-management.md |
Status management description |
scripts/detect_dev_tool.sh |
AI programming tool detection script |
scripts/query_sign_status.sh |
Signing status query and determination script |
scripts/handle_scope_mismatch.sh |
Authorization scope mismatch handling script |
scripts/app_query_and_reuse.sh |
Application query and reuse determination script |
scripts/service_query_and_list.sh |
Service query and list output script |
scripts/upload_screenshots.sh |
Screenshot parallel upload and parsing script |