SuperAPI AI 工具集

setup-adyen

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

该技能面向马来西亚商户的 Adyen 在线支付集成工作,用于搭建、构建、调试、审查和讲解 Adyen 支付集成。

用途与资料结构:技能以 references/adyen-api.md 为入口,包含环境、认证、幂等、端点目录、流程摘要、HMAC 算法、状态、金额、IP 范围、常见错误等主题链接。按任务阅读对应主题文件:adyen-checkout.md(Sessions 流程、Hosted Checkout、Advanced flow、Drop-in、actions、结果码、3DS2)、adyen-webhooks.md(Webhook 设置、载荷、HMAC 校验代码、事件码、重试)、adyen-modifications.md(捕获、退款、取消、冲正、金额更新、生命周期、争议 API)、adyen-payment-methods-my.md(FPX 银行、DuitNow、Touch 'n Go、GrabPay、Boost、Atome、支付宝、Alipay+、微信支付、银行卡)、adyen-tokenization-links.md(令牌与支付链接)、adyen-errors-testing.md(沙箱数据、拒付原因、错误码)、adyen-fields.md(官方 OpenAPI 的完整请求与响应字段表)。账户注册、文档、Customer Area 路径、凭证、环境变量、支付方式激活、提现、报告与上线见 references/account-setup.md;官方页面选择见 references/source-map.md。

核心流程:先确定环境(测试 checkout-test.adyen.com 或 live <PREFIX>-checkout-live.adyenpayments.com),选择流程(Hosted Checkout、Sessions+Drop-in 或 Advanced flow,发票可用支付链接),确认 Customer Area 设置(商户账户、API 凭证角色、API key、带允许来源的 client key、已添加的支付方式、带 HMAC 密钥的 Webhook)。调用 Adyen 前先创建本地待处理订单(金额以 sen 计,MYR)。服务端以 x-API-key、idempotency-key 调用 POST /sessions(或先 /paymentMethods 再 /payments),reference 为订单号,countryCode 为 "MY",并传 returnUrl。前端用 session.id、sessionData 与 client key 渲染 Drop-in,或重定向到 Hosted Checkout URL。返回时提交 redirectResult,resultCode 仅作 UX 展示。逐条验证 Webhook 的 additionalData.hmacSignature(HMAC-SHA256,十六进制解码密钥,8 个字段以 : 连接),存储后 10 秒内返回 2xx,再异步处理。匹配 reference、金额、币种、商户账户与环境后,从 success == "true" 的 AUTHORISATION 幂等结算。捕获、退款、取消与冲正在服务端执行,以其 Webhook 为最终结果。

核心事实:文档使用 Checkout API v72,测试基址 https://checkout-test.adyen.com/v72,live 基址 https://<PREFIX>-checkout-live.adyenpayments.com/checkout/v72(前缀取自 live Customer Area > Developers > API URLs)。认证用 x-API-key 头(Developers > API credentials),client key(test_ / live_)仅用于前端。amount.value 为最小货币单位整数,MYR 两位小数。idempotency-key 最长 64 字符,至少保留 7 天。Webhook HMAC 字符串为 pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success。Webhook 须 10 秒内返回 2xx,重试最长 30 天。修改操作返回 status: "received",结果通过 CAPTURE、REFUND、CANCELLATION、CANCEL_OR_REFUND、TECHNICAL_CANCEL 等 Webhook 送达。FPX 类型为 molpay_ebanking_fpx_MY,须填 issuer,且按 PayNet 规则展示全部 18 家银行。DuitNow 仅支持 QR,结果只经 Webhook;DuitNow 与 Touch 'n Go 需通过 Support 开通。马来西亚本地支付方式不支持循环扣款与单独捕获;Boost 仅支持全额退款。结算时不发 Webhook,需使用 Settlement details 报告。

关键规则:API key、HMAC 密钥与报告凭证仅保留在服务端;client key 是公开的,但需限制允许来源。不得仅凭 resultCode、onPaymentCompleted、redirectResult、sessionResult 或返回 URL 履约。对每条通知用十六进制解码密钥与恒定时间比较验证 HMAC,拒绝无 hmacSignature 的条目。对头部签名的 Webhook(令牌生命周期、Management),基于原始请求体验证。测试密钥配测试主机,live 密钥配 live 前缀主机,并核对 Webhook 的 live 标志。先接收、存储并确认 Webhook,再执行业务逻辑;按 pspReference、eventCode、success 幂等处理。以整数比较 amount.value,并核对 amount.currency 与已存订单。每个 POST 都带 idempotency-key,重试只用同一密钥。展示全部 18 家 FPX 银行,不得过滤 issuer 列表。遵守支付方式限制:GrabPay reference 最长 32 位 [A-Za-z0-9_-];Atome 金额 MYR 10 至 1,500(借记)或 5,000(信用),需必填购物者字段,不支持便携电子产品。不复制费率,链接 https://www.adyen.com/pricing。对官方文档未记录的内容写“官方文档未记录”,不要猜测。

完成标准:服务端以 x-API-key 与 idempotency-key 创建 Session 或支付;前端只渲染 Drop-in 或重定向,不能将订单标记为已付;每个环境配置独立 HMAC 密钥的 Standard Webhook;处理器按文档验证 HMAC、存储、10 秒内确认并异步处理;结算核对 merchantReference、金额、币种、merchantAccountCode、live 与 success;幂等处理重复 Webhook、Pending 之后的迟到 AUTHORISATION、OFFER_CLOSED 及修改失败;测试覆盖错误 HMAC、重放事件、金额或币种不符、拒付、FPX 或钱包待处理、退款失败与成功支付;部署文档列出 ADYEN_API_KEY、ADYEN_MERCHANT_ACCOUNT、ADYEN_CLIENT_KEY、ADYEN_HMAC_KEY、ADYEN_ENVIRONMENT、ADYEN_LIVE_URL_PREFIX、返回 URL、Webhook URL 及测试/生产隔离。

漏洞审查循环:当被问及策略是否“100% 有信心”时,循环执行直至无事实缺口:列出信任边界(浏览器、Drop-in、返回 URL、Hosted Checkout 页面、后端创建方、Adyen API、Webhook 接收器、队列、数据库、履约、修改任务、Customer Area 设置、报告);检查绕过(伪造返回 URL、伪造 Webhook、HMAC 字段错误或密钥未解码、测试密钥用于 live、前缀主机错误、商户账户/金额/币种不符、重复或乱序事件、处理器过慢触发重试、Pending 过早判失败、未捕获先退款、捕获后取消、支付方式未启用、缺少 FPX 银行);补充修复(服务端创建、先本地挂单、按文档校验 HMAC、恒定时间比较、严格字段匹配、持久化事件日志、幂等键、环境隔离配置、基于 DNS 的允许列表、报告对账);对每个缺口重读相关参考文件;说明依赖商户合同、已启用支付方式、live 区域、提现模型或 Support 开通功能的剩余不确定性。

限制:费率、价格等以官方定价页为准;部分支付方式需 Support 开通;未在官方文档记录的内容不提供推测。