SuperAPI AI 工具集

setup-paypal

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途 该技能面向马来西亚注册的 PayPal 企业账户,用于 PayPal 支付集成的搭建、开发、调试、代码审查与解释工作。

主要能力 资料按主题提供参考文件:references/paypal-api.md 汇总马来西亚范围、环境、认证、请求头、金额规则、默认结账流程、状态与完整端点目录;其余文件分别覆盖 Orders v2 与 Payments v2 字段、捕获检查、PATCH 与退款;Webhook 签名验证、请求头、事件与 Webhooks Management API;JavaScript SDK v6 与 v5、回调与服务端路由;订阅的产品、计划、订阅与失败重试;错误码、沙箱、测试卡与负向测试;交易搜索、Payouts(MYR 规则)与争议;账户注册、凭据、环境变量、后台设置与马来西亚账户说明;以及每个事实对应的官方页面来源与已知缺口。

使用方式 先读 references/paypal-api.md,再按任务只加载所需参考文件。核心流程为:识别沙箱或生产环境并使用匹配的凭据、主机、Client ID 与 Webhook ID;识别接入面(JS SDK 按钮、服务端跳转审批链接、订阅、支付链接或 Payouts);在本地创建待支付记录;服务端获取并缓存 OAuth Token,以 intent: CAPTURE、custom_id/invoice_id 和 PayPal-Request-Id 调用 POST /v2/checkout/orders;买家在浏览器完成审批;服务端调用 capture;仅当捕获状态为 COMPLETED 且金额、货币与参考号匹配时才结算;对每个 Webhook 基于原始请求体验签、按事件 ID 去重、重新获取订单或捕获后幂等结算;处理 PENDING 捕获、INSTRUMENT_DECLINED、撤销、退款与争议。

关键事实 REST 基础地址:沙箱 https://api-m.sandbox.paypal.com,生产 https://api-m.paypal.com。Token 通过 POST /v1/oauth2/token 获取,使用 Basic 认证与 grant_type=client_credentials,并在 expires_in 内使用 Bearer。金额是以 {"currency_code","value"} 表示的十进制字符串。MYR 仅对马来西亚本地账户支持为支付与余额货币。订单 COMPLETED 仍可能包含被拒绝的支付,需检查捕获状态。Webhook 支持自验证字符串与 postback 验证,最多重试 25 次、持续 3 天,每个应用最多 10 个 Webhook URL。授权有效期 29 天,含 3 天履约期;退款须在捕获后 180 天内。无公开速率限制,滥用时返回 429。文档列明马来西亚商户不可用的功能包括 FPX、DuitNow、本地电子钱包、Expanded Checkout 卡字段、卡令牌化、Pay Later、PayPal Credit、Venmo 等。

关键规则 客户端密钥仅保留在服务端,只有 Client ID 进入浏览器;订单在服务端创建与定价,不信任浏览器传来的金额;不得依据 onApprove、return_url 跳转或浏览器状态履约;Webhook 必须对原始字节验签并使用同环境 Webhook ID;创建、捕获、授权与退款均使用 PayPal-Request-Id 并在重试时复用;ORDER_ALREADY_CAPTURED 视为“获取并结算”;invoice_id 每单唯一;SDK 的货币与 intent 须与 API 订单一致;设置收款偏好以避免 MYR 或外币付款滞留待人工接受;不得将 API 用于马来西亚的个人付款。

完成标准与审查 集成完成需满足:服务端创建与捕获订单并使用缓存 Token 和请求 ID;浏览器只回传订单 ID,由服务端依据捕获响应或已验签 Webhook 判定支付状态;Webhook 按环境订阅并对原始体验签;结算校验订单 ID、捕获 ID、状态、金额、货币、参考号与环境;重复 Webhook、捕获重试、待处理捕获、撤销与退款均幂等;测试覆盖坏签名、重放事件、INSTRUMENT_DECLINED、待处理捕获、重复 invoice ID、部分与超额退款;部署文档列出环境变量、API 基础地址、Webhook URL 与沙箱/生产隔离。资料另提供“漏洞审查循环”,用于在被问及是否“100% 确信”时逐项检查信任边界、绕过路径与修复措施。

适用场景与限制 适用于马来西亚 PayPal 企业账户的支付集成开发与审查。资料说明部分能力取决于账户资格、收款偏好、费用及未文档化字段,相关不确定性需明确标注。