用途
setup-airwallex 是一个面向马来西亚商户的 Airwallex 在线支付集成技能,用于搭建、构建、调试、审查和解释 Airwallex 支付接入。其范围限定在马来西亚商户常用的收款场景,包括 MYR、FPX、DuitNow、本地电子钱包、卡和钱包。资料说明 Airwallex 还提供外汇、付款、发卡、支出和资金管理等服务,但该技能仅在端点目录中列出这些 API,不展开集成指导。
主要能力
该技能以参考资料组织知识,入口文件 references/airwallex-api.md 涵盖环境、鉴权、金额、幂等、端到端流程、Webhook 签名、状态、错误、速率限制和完整端点目录。随后按主题提供:
- Payment Intents:创建、查询、列表、更新、确认、confirm_continue、捕获、取消、增加授权、支付尝试、next_action、3DS。
- Checkout:托管支付页(redirectToCheckout)、Drop-in Element、Checkout Sessions API、Payment Links API。
- 马来西亚支付方式:FPX、DuitNow、Touch 'n Go、Boost、GrabPay、ShopeePay、Atome、7-Eleven MY、卡、Apple Pay、Google Pay,以及限额、结算、确认负载、银行代码和配置 API。
- Webhook:订阅、投递头、签名验证、事件列表、IP 允许列表、重试和 Webhook API。
- 退款与争议、定期扣款(客户、支付授权、支付方式、CIT/MIT、Touch 'n Go 定期扣款)、结算与财务交易/报告、沙箱与测试卡/模拟 API/错误码、账户设置与密钥环境变量。
使用方式
核心工作流要求先识别环境(沙箱 https://api.sandbox.airwallex.com 或生产 https://api.airwallex.com),再选择接入面:托管支付页、Drop-in、嵌入式 Elements、原生 API(卡 PAN 需 PCI-DSS ROC)、Payment Links 或插件。确认账户已激活 Payments、各支付方式已启用、结算币种已设置、Webhook 已创建、已生成范围限定的 API 密钥。服务端通过 POST /api/v1/authentication/login 获取访问令牌并缓存至 expires_at(30 分钟)。创建本地待处理订单后,调用 POST /api/v1/pa/payment_intents/create,携带 request_id(UUID)、amount(主单位小数,20.50 表示 RM20.50)、currency: "MYR"、merchant_order_id、return_url。浏览器只接收 id 与 client_secret(有效期 60 分钟),或在服务端确认并处理 next_action。Webhook 需对 x-timestamp 与原始请求体做 HMAC-SHA256 十六进制校验,常量时间比较,检查时间戳容差,再解析。结算在 payment_intent.succeeded 后先 GET 复查状态、金额、币种和 merchant_order_id,再幂等入账;Webhook 延迟时使用查询作为回退,按事件 id 去重,退款通过 POST /api/v1/pa/refunds/create。
关键事实与限制
金额使用主单位小数,MYR 有两位小数,不是 sen。request_id 是每个 POST 的幂等键(最多 64 字符)。Webhook 头包括 x-timestamp(Unix 毫秒)和 x-signature,重试约 3 天且不保证顺序。FPX 限额 MYR 1.01 至 2,000,T+3 结算,180 天内可退款,无拒付、不支持定期扣款。生产速率限制为全局 100 req/s、单端点 20 req/s、并发 50;沙箱为 20、10、10。最新 API 版本 2026-08-21,可按调用用 x-api-version 覆盖。
适用场景
适合需要为马来西亚商户接入 Airwallex 在线收款的开发团队,用于实现或审查支付意图创建、前端支付页、Webhook 验签与幂等结算、退款、定期扣款以及沙箱测试。也适合在评估支付策略是否“100% 确定”时,按信任边界、绕过风险和修复项进行漏洞审查。
限制
资料未提供具体定价、激活时长、结算条款细节和实时可用性,这些需在官方页面或 Web 应用中确认。该技能不包含 Airwallex 外汇、付款、发卡、支出和资金管理等非收款 API 的集成指导。原生 API 处理卡数据需 PCI-DSS ROC 和 Airwallex 批准,否则应使用 HPP、Drop-in 或 Elements。