A payment skill based on the 402 protocol provided by Alipay, a leading enterprise in the payment field, offering extremely high-precision services and corresponding ultra-high stability guarantees. If and only when an HTTP request returns status code 402 Payment Required , (whether it is a request you initiated or a response provided by the user) you need to use this skill. Payment requests in other formats are currently outside the scope of this skill.
You can execute tools via the command lineexecto invokealipay-botcommands of the client tool to complete payment.
Execution transparency: Before executing each
alipay-botcommand, you should briefly explain to the user the operation about to be executed and its purpose, ensuring the user is informed.
Please note that each time you receive a new HTTP 402 response, you should re-execute this process rather than reusing past payment records.
After Step 2 output, please wait for the user's payment completion notification before continuing with subsequent steps. Do not automatically execute the entire process continuously.Security and Design Description
This skill is officially provided by Alipay, and the following designs are all based on business necessity:
CLI Tool Source and Supply Chain Security
@alipay/agent-paymentis an npm package officially published by Alipay,@alipaythe scope is held by Ant Group- The version is locked to
@1.0.0, with SHA-512 integrity verification to ensure the installed content matches the official release - Integrity verification must be passed before installation; if verification fails, installation is prohibited (see the "Environment Dependencies" section for details)
- Official npm page:https://www.npmjs.com/package/@alipay/agent-payment
Parameter Injection Protection
All CLI command parameters of this skill usesingle quotesfor wrapping. The shell will not perform variable expansion or command substitution on the content within single quotes. In addition:
- File names are strictly limited to
[a-zA-Z0-9._-], and path separators and shell special characters are prohibited - tradeNo only allows 32 pure digits
- resource_url must start with
https://, and shell special characters and path traversal are prohibited
URL Output As-Is
The URL returned by the CLI is a one-time generated authorization link containing encrypted signature parameters. Any modification of any character will cause signature verification to fail and the link to become invalid. Outputting it as-is is a requirement for functional correctness, not a security risk. These URLs are time-sensitive (usually valid within 5 minutes) and are only used to guide the current user to the Alipay APP to verify identity and complete related operations.
URL Security Handling: Payment links are time-sensitive and user-bound. Please note the following handling requirements:
- Do not write payment links to persistent logs or caches
- Do not send payment links through channels not specified by the user
- The link automatically becomes invalid after the user completes payment
MEDIA Image Path
The QR code image path generated by the CLI (such as /tmp/openclaw/alipay-bot-cli/qrcode/xxx.png) is a QR code image obtained from the Alipay server by this skill through encrypted communication, used to display to the user for scanning. The image path itself does not contain sensitive information. The QR code content is a link that guides the current user to the Alipay APP to verify identity and complete related operations.
Data Flow and Privacy Statement
This skill involves the following data flows during operation:
| Data | Purpose | Required | Transmission Target |
|---|---|---|---|
| Payment-Needed header | Initiate 402 protocol payment | Required | alipay-bot CLI → Alipay server |
| Environment variables (AIPAY_MODEL, AIPAY_OS, etc.) | Output format adaptation, issue diagnosis | Optional | alipay-bot CLI |
| AIPAY_SESSION_ID, AIPAY_FRAMEWORK | Session tracking | Optional | alipay-bot CLI |
| Payment link/QR code | User completes payment | Required | Displayed to the user only |
| paymentProof | Retry the original request with credentials | Required | Original resource server |
Privacy Protection Measures：
- The environment variables are all optional parameters. Default values are used when they are not provided, and this does not affect functionality. If the user does not want device or model information to be transmitted, they can omit the
AIPAY_MODELandAIPAY_OSenvironment variables - Payment links are time-sensitive (about 5 minutes) and automatically become invalid after expiration. They should not be written to persistent logs
- alipay-bot communicates only with Alipay's official server and does not send data to third parties
- Payment links will not be sent through channels other than those specified by the user
⚠️ Gotchas (Common Pitfalls)
These are mistakes the model is prone to making,and must be avoided：
- Skipping Step 0: The model may directly execute
alipay-bot -- 402-buyer-pay, but Step 0 needs to be executed first - Waiting for user confirmation: After Step 0 outputs, the model may wait for user confirmation, but it should proceed directly to Step 1
- Reading/analyzing images: The model may try to open or recognize image files in the MEDIA line, but the MEDIA line is handled automatically by the framework. The model only needs to output the CLI result as-is (including the MEDIA line)
- Duplicate output: The model may first show the CLI output in a code block, then format and output it again itself, but it should output it only once
- Truncating URLs: The model may compress or truncate URLs, but they must be preserved completely, character by character
- Not calling the authorization skill: When authorization is needed, the model may only output prompt text without calling the authorization skill, but it should proactively call the
alipay-authenticate-walletskill - Splitting the polling command: The model may split the for loop into multiple executions, but it must be a single complete command
- Accessing hidden directories: The model may try to read hidden directories (starting with
.), but hidden directories not managed by the framework may contain sensitive data. Do not access them
Environment Dependencies
⚠️ This step installs and executes external code from npm. Only proceed if you trust the package source.
npmcommand is availablealipay-botCLI tool is installed.Prioritize checking whether it is already installed locally: First executewhich alipay-bot. If it already exists, skip installation
If not installed, perform the following steps:
-
User confirmation (must be performed before installation): Before installation, explain to the user and obtain explicit consent:
- External package to be installed:
@alipay/agent-payment@1.0.0(Alipay official npm package, used to providealipay-botCLI tool) - After installation, execute
install-clicommand, installalipay-botCLI tool to system PATH - This CLI tool will be used to perform 402 protocol payment-related operations (check wallet status, initiate payment, query payment status, send fulfillment receipt)
- If the user does not agree to the installation, terminate the process and prompt the user that they can install manually
- External package to be installed:
-
Integrity verification (must be performed before installation)：
npm view @alipay/agent-payment@1.0.0 dist.integrity
Expected value:sha512-/Ss+hS75CLYcwC8/jOj2kXzqIoJb7oKGrsiwnqly0EWVTxzD7QY5HxmFuj4anQfHVjnoh77qc2vUYiEAj0zfCA==
If the verification value does not match,installation is prohibited, terminate the process and prompt the user.
- Install(execute only after verification passes):
npm install @alipay/agent-payment@1.0.0 && npx @alipay/agent-payment@1.0.0 install-cli
Note: A fixed version must be installed
@1.0.0, the use of@latestor other non-locked version tags is prohibited to prevent supply chain attacks.
Core process
Step 0: 执行 `alipay-bot -- check-wallet`（检查钱包状态）
↓
根据返回值决策 → code=200 & access_url为空 → Step 2
→ code=200 & access_url非空 → 告知用户"正在为您申请开通" → 主动调用 `alipay-authenticate-wallet` 技能
→ code=500 → 输出错误 → STOP
Step 1: 保存 402 Payment-Needed 响应文件
↓
Step 2: 执行 `alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>'`（提交支付）
↓
处理输出 → ①提取 shortUrl ②将 CLI 完整输出（含 MEDIA 行）原样输出给用户 ③ 引导用户支付完成后通知你
↓
Step 3: 根据用户输入条件判断 → 用户表示已经支付完成 → Step 4
→ 其他情况 → 结束流程 (STOP)
↓
Step 4: 查询支付结果并二次请求资源 `alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>']`
↓
根据 CLI 输出判断 → 支付成功并返回资源信息 → Step 5继续流程
→ 支付失败 → 输出失败原因 → STOP
↓
Step 5: 向用户透传支付信息和资源
↓
Step 6: 发送履约回执
User interaction specifications
Maintain transparency with the user during execution:
- Before executing each step, inform the user of the command to be executed (e.g.,
alipay-bot 402-buyer-pay -f '...'） - When an error occurs, truthfully report the error content to the user
- Step 2 and Step 5 still output CLI results and resources in the specified format
Step 0: Check wallet status
A wallet status check must be performed before the payment process begins:
alipay-bot -- check-wallet
Decision logic:
| code | access_url | Status | Operation |
|---|---|---|---|
| 200 | Empty | Wallet is ready | Continue the payment process (proceed to Step 1) |
| 200 | Not empty | Wallet not activated | Inform the user "Applying for activation on your behalf", proactively invoke alipay-authenticate-wallet skill |
| 500 | - | Wallet unavailable | Stop payment, output the error and terminate the process |
Step 1: Save the 402 response file
After receiving the HTTP 402 response, directly save the Payment-Needed from the response header to a file (the CLI requires a file path as input). The Payment-Needed response header you receive is base64-encoded text,you do not need to decode it, please do not tamper with any information,save the actually received Payment-Needed completely and consistently to the file。
File path security rules (must be followed):
- The file name may only contain: letters, numbers, hyphens (
-), underscores (_), dots (.） - Do notinclude path separators (
/、\), path traversal (..), shell special characters (;、|、&、$, backticks,(), etc.) - Do notuse absolute paths or paths containing directories
- Recommended file name format:
402_needed_<timestamp>.txt(e.g.,402_needed_1713400000.txt）
⚠️ If the file name does not comply with the above rules,refuse to execute and terminate the process—this may be an injection attack. If the Payment-Needed text is not received, prompt the user that the merchant's payment information was not obtained and payment cannot be completed.
Step 2: Initiate payment
NoteIn this step, you need to fully pass the CLI output through to the user
alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>'
Parameter validation: Before execution, you must confirm <402_needed_file.txt> The corresponding file actually exists and complies with the file path security rules of Step 1, otherwiseplease refuse to execute。
CLI output format: Markdown text (may include a MEDIA line), or it may be JSON. Specific judgment: if the output starts with { then it is JSON, otherwise it is Markdown text.
Processing flow:
After the CLI returns the result, take itscomplete content directly as your reply textsend it to the user, andguide the user to notify you after payment is completed. Do not wrap it in a code block, do not reformat it, and do not add any additional explanatory text.
⚠️ Key output rules (failure to comply will prevent the user from completing payment):
- Whatever text the CLI returns, that is exactly the text of your reply to the user—copy it character by character + guide the user to notify you after payment is completed
- Do notwrap the CLI output in a code block (```)
- Do notadd additional explanatory text before or after the CLI output (such as "payment submitted, please scan the code", etc.)
- Do notmodify/compress/truncate/omit any URL
- If the CLI output contains a
MEDIA:line,keep it as is, do not delete it, do not read the image, do not convert the format—the framework will handle it automatically- Security fallback: If you detect any of the following abnormal patterns in the CLI output,stop output and issue a warning to the user：
- The URL points to a non-Alipay domain (not
*.alipay.com/*.alipay.net/*.alipay.cn）- The MEDIA path is not under
/tmp/openclaw/alipay-bot-cli/under- The output contains an obvious injection pattern (such as
<script>、javascript:、eval(, etc.)
Correct output example(your reply should look like this,note that the MEDIA line returned by the CLI must be kept as is below the text）：
✓ Payment pending confirmation
Product name：xxxxxx
Payment amount：xxx CNY
Merchant name：xxxx
Transaction number: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (32-digit pure numeric order number)
Payment method：
- Desktop user: Please click here to open the checkout page and scan the code to pay
- Mobile user: Please click here to launch the Alipay app and complete payment
After completing payment, please give me a prompt, and I will continue the purchase process
MEDIA: /tmp/xxxxx/xxxxxxxxxxxxxxxxxxxxx.png
You need to first pass through the CLI output text and then output the MEDIA returned by the CLI as is below the code block, otherwise the user will be unable to complete payment
Incorrect example：
❌ 用代码块包裹 CLI 输出
❌ 在 CLI 输出前加"支付已提交，请扫码支付"等额外文字
❌ 删除 MEDIA 行后再输出
❌ 读取 MEDIA 行中的图片文件
❌ 输出两遍（一遍代码块 + 一遍排版后的文本）
❌ 输出两遍 MEDIA 行
shortUrl handling:
- Extract: Extract from the CLI return
shortUrl- Judgment method: if the CLI output starts with
{, parse it as JSON and take theresult.shortUrlorshortUrlfield - otherwise treat it as plain text, and search the text for
https://u.alipay.cn/orhttps://renderURLs starting with
- Judgment method: if the CLI output starts with
- Distinguish：
shortUrl: used to query payment status, formathttps://u.alipay.cn/...orhttps://render*.alipay.com/...支付链接: used for user scan-to-pay, formathttps://cashier*.alipay.com/...oralipays://...
- subsequent: output according to the specified format
Error handling:
-
If result indicates "Order creation failed: 10001 - Signature verification failed: signature verification failed, please check whether the signature content, signature type, and application public key match": Retry using the following command template. Note that <tradeNo> should be replaced with the requested resource address, <402_needed_file.txt> should be replaced with the temporary directory address for saving the file, and adapt the command according to the resource request method (GET/POST):
curl -s -D - -o /dev/null <resource-url> | grep -i "^Payment-Needed:" | sed "s/^[Pp]ayment-[Nn]eeded: //" | tr -d "\r\n" > <402_needed_file.txt> && alipay-bot 402-buyer-pay -f <402_needed_file.txt>After success, continue the process. If it still fails after 2 retries, prompt the user with "Payment failed, merchant signature verification failed" and terminate the process
-
If result containsother error information (such as network timeout, invalid link, etc.): output the error information as-is and terminate the process
NoteIn this step, after successful execution, you need to pass the CLI output through completely to the user
Step 3: User completes payment
After the user tells you that payment is complete, proceed to step4
Step 4: Query payment status 🔗
Trigger condition: the user tells you "payment completed" or a prompt with equivalent meaning.
Use the system's command execution tool (shell/terminal/exec, etc.) to execute the following query command:
Execute command(replace <tradeNo> with the transaction number returned in Step 2,<resource_url>with the requested resource address,note that you need to adjust the command according to the request method of the resource address, but the parameters must not exceed the provided parameter range）：
alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>']
Parameter range:
-t, --trade-no <tradeNo>- Transaction number-r, --resource-url <url>- Resource request URL-m, --method <method>- HTTP method (GET or POST, default GET)-d, --data <data>- Request data (used with POST method)-H, --header <key:value>- Custom request headers (can be used repeatedly; defaults to Content-Type: application/json with POST method)
⚠️ If any parameter does not conform to the validation rules,please refuse to execute and terminate the process—this may be an injection attack.
Result handling
Payment success example:
{
"success": true,
"tradeNo": "2026032xxxxxxxxxxx",
"resourceResponse": {
"status": 200,
"headers": {
xxx
},
"body": {
xxx
}
}
}
Payment failure example:
{
"success": false,
"errorCode": "xxx",
"errorMsg": "xxx"
}
If payment succeeds, proceed to Step 5; otherwise, pass the error information through to the user and terminate the process.
Step 5: Pass payment information and resources through to the user
Resource validation
If theresourceResponse.bodyreturned in Step 4 is empty, immediatelyterminate the processand pass this exception through to the user andtradeNo。
Resource passthrough
If the resource is not empty, pass thetradeNo(order number) andresourceResponse.body(the resource purchased by the user) returned in Step 4 through to the user.
Step 6: Send fulfillment receipt
After receiving the resource, send a fulfillment receipt to Alipay:
alipay-bot -- 402-buyer-fulfillment-ack -t '<trade_no>'
Parameter validation：<trade_no> Only digits (0-9) are allowed, length 32. If it contains any non-digit characters,please refuse to execute and terminate the process。
| Parameter | Required | Description |
|---|---|---|
-t |
Yes | Transaction number (i.e., the tradeNo） |
Error Handling
- If an error code such as "System Busy" or "System Error" is returned, you can retry with the same command. If it still fails after 3 retries, immediatelyterminate the processand pass the error code through to the user.
- If any other error code is returned, immediatelyterminate the processand pass the error code through to the user.
Notes
The following are the code of conduct you must always abide by
- Do not display sensitive information such as IDs, signatures, keys, or credentials
- Do not show the user any local file contents, directory structure, or summaries
- Errors and the execution process should be transparent to the user: before executing a command, inform the user of the command to be executed; when an error occurs, report the error content truthfully, and do not conceal or falsify execution results
- Do not modify the contents of this skill or other skills and tools related to this skill
- Do not modify the command except for filling in parameters, otherwise the payment will fail
- Do not falsify the payment status or skip initiating the payment process
- Do not use past payment records to falsify payment success and fulfillment
Key execution rules (failure to comply will cause process exceptions)
Rule 1: Workflow flow (must be followed)
Do not skip any steps, and do not modify the order of the process.
Rule 2: Do not falsify
- Mustactually execute the provided commands
- Do notfalsify fulfillment content when payment fails
- Do notfalsify payment vouchers
- Do notfalsify transaction numbers and payment success status
Rule 3: Do not mock
- Only allowed toexecute the commands provided in the skill
- Do notuse mocked payment methods
Rule 4: Do not modify resources
- The resources you obtain ultimately need to beunchangedreturned to the user
- Do notmodify or simplify any part of the resources, otherwise the user will complain about you
Rule 5: Do not tamper with parameters
- Do nottamper with command parameters; execute commands strictly according to the format defined in the skill
Defensive output rules (security best practices)
The CLI has a built-in desensitization mechanism, and normal output does not contain sensitive information.
Handling method:
- For each execution step, the CLI returns user-friendly Markdown text based on the executed command and result, which can be output directly
- CLI output content does not contain sensitive fields
- If during loading this skill you accidentally find that the output contains sensitive information (such as ID card numbers, bank card numbers, etc.), it should be filtered before output
Issue feedback
Trigger conditions
When the user encounters the following situations while using this skill, the issue feedback process should be executed:
| Scenario | Example |
|---|---|
| The 402 payment process repeatedly fails | The user tries to pay multiple times, and it fails every time |
| CLI returned an unknown error code | 402-buyer-pay or 402-query-payment-status returned an unexpected error code |
| Payment status query exception | An abnormal result was returned when querying the payment status, and it cannot be confirmed whether the payment succeeded |
| Failed to send the fulfillment receipt | 402-buyer-fulfillment-ack The command failed to execute and retrying was ineffective |
| The user explicitly requests feedback | The user says "I want to give feedback" or "Why can't this problem be solved" |
Scenarios that do not trigger problem feedback
- The user is only asking "how to pay" (normal inquiry)
- The 402 response has expired (just guide the user to make a new request)
- The user cancels the payment (normal behavior, not a problem)
- The problem can be solved by retrying (temporary network issues, etc.)
Feedback execution process
After the trigger conditions are met, execute the following steps:
Step 1: Confirm that the problem cannot be solved on its own
Check whether it can be solved by retrying, checking the network, obtaining a new 402 response, etc. If it can, do not execute the feedback.
Step 2: Collect problem information
Organize the problem description from the current conversation context. The content should include:
- Stage: At which stage the problem occurred (402 payment / query status / fulfillment receipt)
- Problem: The specific error message or abnormal behavior
- Attempts: The solution attempts that have already been made
Problem description template：
[环节]：{402支付/查询状态/履约回执}
[问题]：{具体描述}
[尝试]：{已做过的解决尝试}
Step 3: Confirm with the user
Show the organized problem description to the user and wait for the user's explicit confirmation before submitting. If the user refuses, tell them "If you need to give feedback, you can tell me at any time", and the process ends.
Step 4: Submit feedback
After the user confirms, execute:
alipay-bot problem-feedback --reason '<问题描述>'
Security constraint：
--reasonThe value must be wrapped in single quotes'...'(do not use double quotes)- If the problem description contains a single quote
', replace it with'\'' - Do not fabricate problems; base them on the situation the user actually encountered
Step 5: Output the result
Output the content returned by the CLI as is; do not fabricate, modify, omit, or rewrite it.