agent-1yuan-purchase-skill/references/payment-flow.md

支付+轮询+交付详细流程

3.1 获取 Payment-Needed

在创建订单后，调用获取支付参数接口：

curl -s -X POST "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
  -H "Accept: application/json" \
  | grep -i "^Payment-Needed:" \
  | sed "s/^[Pp]ayment-[Nn]eeded: //" \
  | tr -d "\r\n" \
  > 402_needed_file.txt

失败处理：

• 返回非 402 状态码或不包含 Payment-Needed 头 → 提示"获取支付参数失败" → 终止流程

3.2 提交支付

alipay-bot 402-buyer-pay \
  --session-id "<session-uuid>" \
  -f "402_needed_file.txt" \
  -r "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
  --intent-summary "原始请求：用户购买软件订单：{orderNo}" \
  -m POST

输出判断：

CLI 输出	动作
含 ✓ 支付待确认 + 二维码	展示给用户 → 进入 3.3 轮询
含 ✓ 支付成功并获取资源	跳过轮询 → 直接进入 Step 4
含 ✗ 支付失败	原样输出 → 终止
其他错误 JSON	原样输出 errorMsg → 终止

可重试错误（最多3次）：

• SERVER_TIMEOUT / CLIENT_TIMEOUT / SYSTEM_ERROR / SYSTEM_ERR
• POLL_INTERRUPTED / PAY_SUBMIT_FAILED / PAY_STATUS_UNKNOWN

不可重试错误（直接终止）：

• SERVICE_SELLER_ID_MISMATCH（卖家ID不匹配）
• BUYER_SELLER_SAME（买家和卖家相同）
• REQUEST_EXPIRED（请求过期）
• 其他未识别错误码

3.3 自动轮询

支付发起后自动轮询，不需要用户手动通知"已支付"：

import time, subprocess, json

def poll_payment_status(trade_no, resource_url, max_wait=180, interval=5):
    """自动轮询支付状态"""
    elapsed = 0
    
    while elapsed < max_wait:
        time.sleep(interval)
        elapsed += interval
        
        # 执行查询命令
        result = subprocess.run([
            "alipay-bot", "402-query-payment-status",
            "-t", trade_no,
            "-r", resource_url,
            "-m", "POST"
        ], capture_output=True, text=True)
        
        try:
            data = json.loads(result.stdout)
            if data.get("success") == True:
                return {"status": "success", "data": data}
        except (json.JSONDecodeError, KeyError):
            pass
        
        # 每30秒输出进度
        if elapsed % 30 == 0:
            print(f"⏳ 正在等待支付确认...（已等待{elapsed}秒）")
    
    return {"status": "timeout"}

轮询结果处理：

• success=true → 进入 Step 4 交付
• 超时 → 提示"支付等待超时，请稍后重试"
• 命令失败 → 重试1次，仍失败则终止

Step 4：交付文件

4.1 获取交付链接（网盘链接）

# 构造 Payment-Proof
PROOF=$(python -c "
import json, base64
proof = {
    'protocol': {'payment_proof': 'verified', 'trade_no': '<trade_no>'},
    'method': {'client_session': base64.b64encode(b'agent-session').decode()},
}
print(base64.urlsafe_b64encode(json.dumps(proof).encode()).decode())
")

# 调用验证接口获取网盘链接
curl -s -X POST "{STORE_BASE_URL}/api/orders/{orderNo}/verify" \
  -H "Content-Type: application/json" \
  -H "Payment-Proof: $PROOF" \
  -d "{\"paymentProof\": \"$PROOF\"}"

4.2 履约回执

alipay-bot 402-buyer-fulfillment-ack -t '<trade_no>'

可重试错误（最多3次同 trade_no 重试）：

• TR_FULFILLMENT_FAILED / FULFILLMENT_FAILED / SYSTEM_ERROR / SYSTEM_ERR

不可重试错误：

• 原样输出 errorMsg + trade_no → 终止

4.3 通知用户

✅ 支付成功！
订单号：{orderNo}
交易号：{trade_no}

🎉 您的软件提取信息如下：
🔗 网盘地址：{返回的 downloadUrl}
🔑 提取码：{若有提取码则展示}

⚠️ 注意：请在有效期内尽快保存或下载，不要分享给他人。

交易号校验

• 必须恰好 32 位纯数字
• 校验不通过 → 输出"交易号格式异常" → 立即终止
• 禁止对非32位 trade_no 执行任何后续命令