用途
该技能面向 Atome(apaylater)线上先买后付(BNPL)集成工作,可辅助搭建、开发、调试、审查和讲解 Atome 支付接入。使用前应先阅读 references/atome-api.md,其中包含端点目录、基础 URL、Basic 认证、10 步结账流程、创建支付与嵌套字段表、支付对象与状态、重查、取消、退款、回调字段、X-Signature 的 HMAC-SHA256 校验、IP 白名单、金额规则、枚举、完整错误码表及测试说明。
主要能力与参考资料
- 商户使用 Shopify、WooCommerce、Magento、PrestaShop、OpenCart、EasyStore、Wix 或 Salesforce 时,或在 iOS、Android、React Native、Flutter 应用中打开 appPaymentUrl 时,查阅 references/atome-plugins-sdk.md。
- 用户询问注册方式、凭据来源、测试与生产配置、环境变量名、插件、马来西亚相关事项、定价或结算时,查阅 references/account-setup.md。
- 需要判断适用哪个 Atome 官方页面,或查看只能由 Atome 客户经理回答的缺口清单时,查阅 references/source-map.md。
核心工作流
- 确认环境:测试(api.apaylater.net)或生产(api.apaylater.com)。
- 确认接入面:原生 API(Web 重定向或应用 appPaymentUrl)或平台插件。
- 从 Atome 客户经理处确认凭据:API 用户名、API 密码、回调签名密钥及其编码方式。
- 以 countryCode: "MY" 和回调 URL 调用一次 POST /auth,验证凭据与回调可达性。
- 先在本地创建待处理支付,再在服务端调用 POST /payments,传入唯一 referenceId、以 sen 为单位的 MYR 金额、callbackUrl、paymentResultUrl、paymentCancelUrl、customerInfo.mobileNumber、shippingAddress 和 items。
- 将客户引导至 redirectUrl(浏览器)或 appPaymentUrl(应用内,通过 SDK)。
- paymentResultUrl 与 paymentCancelUrl 仅用于浏览器用户体验。
- 收到回调时,基于原始请求体验证 X-Signature,读取 referenceId,然后调用 GET /payments/{referenceId}。
- 仅当查询到的状态为 PAID,且 referenceId、金额、币种和环境均匹配时,才幂等地完成结算。
- 自有结账保留期到期时调用 cancel;退款使用唯一 refundId。
核心事实
- 测试基础 URL:https://api.apaylater.net/v2;生产基础 URL:https://api.apaylater.com/v2;要求 TLS 1.2+。
- 认证:Authorization: Basic base64(username:password),由 Atome 客户经理签发。
- 端点:POST /auth、POST /payments、GET /payments/{referenceId}、POST /payments/{referenceId}/cancel、POST /payments/{referenceId}/refund。
- POST /payments 以 referenceId 幂等(格式 [0-9a-zA-Z-_]{1,40})。
- 金额为最小货币单位的整数;MYR 为 sen。MYR 最低为 RM10.00(1000),最高值文档未说明。
- 创建支付必填字段:currency、amount、callbackUrl、paymentResultUrl、customerInfo(mobileNumber 需为 E.164 格式)、shippingAddress(countryCode、lines、postCode)、items(itemId、name、quantity、price)。
- 未支付订单默认 12 小时后自动取消(默认值即最大值);expirationTime 可缩短,最短 300 秒。
- 状态:PROCESSING、PAID、FAILED、CANCELLED、REFUNDED。
- PAID 表示已收到首期付款;即使后续分期逾期,仍保持 PAID。
- 部分退款保持 PAID;全额退款变为 REFUNDED。退款为同步操作,按 refundId 幂等。
- 回调请求体仅为 {"referenceId": "..."};Atome 在 5 小时内重试 5 次,之后邮件通知商户。
- 回调使用共享密钥对原始请求体做 HMAC-SHA256,签名位于 X-Signature 头;编码和密钥由客户经理提供。
- 马来西亚回调来源 IP:47.254.230.20、47.254.238.153;测试环境为 47.254.247.54。
- 在马来西亚,购物者在 Atome 应用内完成支付(开发者门户 FAQ 将 MY 列为仅应用内)。
关键规则
- API 密码与回调密钥仅保存在服务端。
- 绝不依据 paymentResultUrl、应用返回或回调体标记已支付;始终以 GET /payments/{referenceId} 的查询结果为准。
- 解析 JSON 前,针对原始请求字节验证 X-Signature,并使用常量时间比较。不得猜测十六进制或 Base64 编码,需与 Atome 确认。
- 重定向前保存 referenceId、预期金额(sen)、币种、环境和本地订单 ID。
- 超时或 5xx 后重试创建时,复用同一 referenceId;仅在真正的新尝试时生成新 ID。
- 持久记录后向回调返回 HTTP 200;保证 5 次重试下的处理幂等。
- 若结账库存或预订保留时间短于 12 小时,到期时调用 cancel;若 cancel 返回 PAYMENT_NOT_CANCELLABLE,则重查并履约或退款。
- 不得发送小数金额;12.34 无效,应发送 1234。
- 依据错误码分支处理,不得依据消息文本。
- 不得混用测试凭据与生产基础 URL,反之亦然。
- 不得因购物者错过后续分期而撤销订单。
完成标准
集成完成需同时满足:POST /auth 在目标环境以 countryCode: "MY" 成功;POST /payments 在服务端执行,使用 Basic 认证、已存储的唯一 referenceId,金额以 sen 为单位且不低于 RM10.00;浏览器重定向仅展示“确认中”页面并触发服务端重查,绝不履约;回调处理程序验证 X-Signature(使用已确认的编码)、重查并幂等结算;结算校验状态 PAID、referenceId、金额、币种、环境和本地订单归属;cancel 与本地结账过期绑定;退款发送唯一 refundId 并处理 AMOUNT_NOT_VALID 和 UNABLE_TO_REFUND;测试覆盖无效签名、重复回调、未知 referenceId 回调、FAILED、CANCELLED、部分退款(保持 PAID)、全额退款(REFUNDED)及成功 PAID;部署文档列出 ATOME_BASE_URL、ATOME_API_USERNAME、ATOME_API_PASSWORD、ATOME_CALLBACK_SECRET、回调 URL、结果与取消 URL,以及测试与生产分离。
漏洞审查循环
被问及 Atome 策略是否“100% 确定”时,运行该循环直至无事实缺口:列出信任边界(浏览器、商户应用 WebView、后端支付创建器、Atome API、Atome 应用、回调接收器、原始请求体解析器、数据库、履约任务、退款任务、取消任务、插件设置);检查绕过路径(伪造 paymentResultUrl 访问、伪造回调、对解析后 JSON 验签、错误密钥或编码、测试生产混用、小数金额、低于 RM10.00、跨订单复用 referenceId、过期重查、重复回调、本地保留过期后支付完成却未取消、无 refundId 的重复退款、退款超过 refundableAmount、Atome 账户未激活导致退款受阻、防火墙拦截 Atome IP);补充修复(服务端创建、先写本地待处理记录、原始体 HMAC 校验、强制重查、严格金额/币种/reference 匹配、以 referenceId 为键的幂等结算、到期取消、refundId 幂等、环境配置分离、IP 白名单、/auth 连通性测试);重读 references/atome-api.md 中与缺口相关的章节;若不确定性取决于回调密钥编码、最大金额、MDR、结算周期、速率限制、测试购物者账户或商户合同条款,需说明。
适用场景与限制
适用于 Atome 马来西亚 BNPL 的接入开发、调试、代码审查与方案讲解,含插件与移动应用内支付场景。相关事实以技能附带参考文档为准;定价、MDR、结算周期、最大金额、速率限制、测试账户及合同条款等未在资料中充分提供的细节,暂未提供,需向 Atome 客户经理确认。