主题
Alipay+ / Antom 配置（东南亚钱包）
一句话
接一个 Antom，买家就能用 GCash、TrueMoney、DANA、Touch n Go、KakaoPay、支付宝 等一批本地钱包付款 —— 不用一个个去谈。
整件事其实只有四步
别被下面的篇幅吓到 —— 正常情况下你只需要复制粘贴四个值， 后面那些长篇都是"万一出问题查哪里"，不用先读。
- 去 https://www.antom.com/ 注册，集成方式选 CKP 全托管式
- 打开控制台的「快速开始」，右侧卡片上就有三个值；私钥在「密钥配置」里
- 后台 → 站点管理 → 支付通道 → 新增 Alipay+，填四个值，点「测试连接」
- 下一单沙箱走一遍
没有任何命令行操作，也不需要开发介入。 卡住了就翻到最后那张 排错表，上面是系统会弹给你的原话。
什么时候需要它
Stripe 和 PayPal 在东南亚的覆盖是有限的：印尼、菲律宾、泰国、马来西亚的买家 很多人没有信用卡，用的是手机里的电子钱包。
| 你的目标市场 | 建议 |
|---|---|
| 欧美为主 | Stripe + PayPal 够了，不用接这个 |
| 东南亚 / 港澳台 / 韩国 | 加一个 Antom，转化率差别很大 |
| 全球都卖 | 三个都开，买家在结算页自己挑 |
这不是"多一个按钮"那么简单
每多一个支付通道，上线前就多一套要测的东西（真实下单、真实退款、回调）。 没有明确的东南亚订单需求时，先不要接。
和 Stripe / PayPal 最大的三点不同
① 回调地址不用你去填
Stripe 和 PayPal 要你在它们后台建一个 webhook 端点。Antom 不用 —— 系统在每一笔请求里都带上回调地址，Antom 按那个地址回。
控制台里那一格怎么办
Antom 控制台里如果有「通知地址 / Notification URL」这一格： 留空或随便填都行，以我们每笔请求带的为准。
如果它是必填项，填这个（通道ID 在后台建完通道后，通道列表里能看到）：
https://你的域名/api/open/payment/callback/antom/通道ID这样设计是有原因的：换收款账号之后，老订单的回调仍然会打回老通道， 拿得到当时那套密钥去验签。填死一个全局地址就做不到这一点。
② 你要保管一把私钥
Stripe / PayPal 给你的是「密钥字符串」，丢了随时能回它们后台再看一次。 Antom 是非对称加密：控制台帮你生成密钥对，但私钥只显示那一次，Antom 自己不保存。
私钥丢了只能重新生成一对
丢了 = 重新生成密钥对 + 重新上传公钥 + 重新在后台填一遍。 过程中支付会中断。生成完立刻离线备份一份。
③ 沙箱和正式的 Client ID 长得不一样
沙箱的以 SANDBOX_ 开头，正式的没有这个前缀。
系统会强制检查这两件事一致：通道的「环境」开关选了沙箱，Client ID 就必须是 SANDBOX_ 开头的；不一致会直接拒绝，并告诉你是哪一边不对。
为什么要卡这么死
不卡的话最坏的情况是：通道标着「正式」、握着沙箱密钥 —— 测试单混进真实营业额， 而报表数字"看着差不多对"，是最难发现的一类错误。
你要拿的四个值
| 后台字段 | 长什么样 | 在 Antom 哪里 |
|---|---|---|
| 网关地址 | https://open-sea-global.alipay.com | 快速开始 → 测试集成资源 →「网关端点」 |
| Client ID | SANDBOX_5XXX...（沙箱） | 同一张卡片 →「Client ID」 |
| Antom 公钥 | MIIBIjANBgkqhkiG9w0... | 同一张卡片 →「Antom公钥」 |
| 商户私钥 | MIIEwA...（长四倍） | 开发者 → 密钥配置（只显示一次） |
Antom 给你的是三段，只有两段要填
控制台上「Antom公钥」和「您的公钥」是挨在一起列的，长得几乎一模一样。 按标签认，别按位置认：
| 标签 | 长度 | 开头 | 结尾 | 填到哪 |
|---|---|---|---|---|
| Antom 公钥 | 392 | MIIBIj | IDAQAB | →「Antom 公钥」 |
| 您的公钥 | 392 | MIIBIj | IDAQAB | 哪都不填（这是你上传给 Antom 的） |
| 商户私钥 | 约 1628 | MIIE | 各不相同 | →「商户私钥」 |
私钥一眼就能认出来：它比公钥长四倍。 只要「商户私钥」那格里的东西不到四百字符、 或者以 MIIBIj 开头，就一定是填错了。
而两把公钥的指纹完全一样（都是 392 / MIIBIj / IDAQAB）， 没有任何办法从内容上分辨 —— 只能靠 Antom 控制台上那个标签。复制的时候看准了。
填反了会怎样
- 公钥填进「商户私钥」：一个请求都发不出去。系统会直接告诉你 「你填的是一把公钥（长 392，MIIBIj 开头、IDAQAB 结尾）。私钥要长得多——约 1600 字符、MIIE 开头」。
- 私钥填进「Antom 公钥」：同样当场报错点名。
- 两把公钥搞混（填了「您的公钥」而不是「Antom公钥」）：★ 这个测试连接查不出来， 下一节会讲 —— 要等第一笔真实回调才发作，而那时钱已经收了。
网关地址填错，每一笔都会失败
Antom 按区域分了好几个网关，填错区域的报错看不出是区域问题。 以控制台上写的那个为准，别照抄别人的。
| 区域 | 网关 |
|---|---|
| 东南亚 | https://open-sea-global.alipay.com |
| 美洲 | https://open-na-global.alipay.com |
| 欧洲 | https://open-eu-global.alipay.com |
| 全球 | https://open-global.alipay.com |
第 1 步：注册，然后打开「快速开始」
- 去 https://www.antom.com/ 注册商户账号
- 登录后直接打开这一页：开发者 → 快速开始 （https://dashboard.antom.com/global-payments/developers/quickStart）
你要的东西基本都在这一页上。 页面右侧有一张「测试集成资源」卡片， 四个值里的三个直接列在上面，复制就行：
| 卡片上的标签 | 对应后台哪一格 |
|---|---|
| 网关端点 | 网关地址 |
| Client ID | Client ID |
| Antom公钥 | Antom 公钥 |
| 您的公钥 | 哪都不填（这是你上传给 Antom 的那把） |
需要企业主体
Antom 面向企业商户，注册要提供公司资料（营业执照 / 注册证明、法人身份、对公账户）， 个人开不了。
但审核和激活不挡开发 —— 注册完就能拿到上面那套沙箱资源，整条链路先跑通再说。
集成方式选「CKP 全托管式集成」
页面中间的「集成引导」第一步要你选集成方式，选错后面全对不上。
本系统接的是 CKP 全托管式（收银台托管页）：买家整页跳到 Antom 的页面， 上面列着各个钱包，他自己挑。
其它几种都不要选 —— 代扣 / 订阅要先签约，线下扫码是给收银机器用的， 嵌入式组件要在我们页面里嵌它的 JS（本系统没接这种）。
「集成引导」的 5 步，你只需要做前 3 步
- 选集成方式 → CKP 全托管式
- 沙箱集成 → 就是拿上面那几个值填进我们后台
- 集成用例测试 → 下一单沙箱走通就算过
- 切换至生产模式 → 要先激活商家账户（见下）
- 集成上线
前三步做完，沙箱就能完整收款和退款了。
想收真钱要先「激活账户」
账户没激活时，第 4 步是灰的点不动，页面上会写 「检测到您的商家账户暂未激活，还无法切换生产模式。请联系您的业务人员激活账户」。
这一步不是技术问题，是商务流程 —— 找 Antom 的对接人推进。 在那之前顶部一直挂着「你正在使用测试数据，不会处理任何真实的交易」。
第 2 步：拿私钥
四个值里只有商户私钥不在「快速开始」那张卡片上 —— 它在左边菜单的 开发者 → 密钥配置 里。
私钥只显示一次
Antom 不保存你的私钥，只在生成那一刻显示一次，刷新就没了。 当场复制到安全的地方（密码管理器 / 加密笔记），别只留在浏览器标签页里。
丢了不是灾难，但要重新生成一对、重新在后台填一遍，中间支付会中断。
不用管格式，粘进去就行
-----BEGIN PRIVATE KEY----- 那两行头尾、中间的换行、前后多余的空格 —— 带着一起粘贴都没问题，系统会自己清掉。
公司规定必须自己生成密钥？（一般人不用看）
少数商户的安全规范要求私钥不能由第三方生成。这种情况下自己生成一对， 把公钥上传到「密钥配置」：
bash
openssl genrsa -out private.pem 2048 && openssl pkcs8 -topk8 -inform PEM -in private.pem -outform PEM -nocrypt -out private_pkcs8.pem && openssl rsa -in private.pem -pubout -out public.pem上传 public.pem 的内容，后台「商户私钥」填 private_pkcs8.pem 的内容。 ★ 必须是 PKCS#8（private_pkcs8.pem），直接用 private.pem 是 PKCS#1，系统会拒绝并提示你转换。
控制台自带的排查工具（出问题时很有用）
左边菜单 开发者 下面：
- 请求日志 —— 我们发给 Antom 的每一个请求和它的回复，报错原文在这里
- 通知日志 —— Antom 回调我们的记录，「支付成功了订单没变」时看这里
- API 调用模拟 / 错误场景模拟 —— 手动造一个请求或一个失败场景
第 3 步：在后台建通道
后台 → 站点管理 → 支付通道 → 新增
- 支付方式选 Alipay+
- 环境先选 沙箱
- 把上面四个值填进去
- 点「测试连接」
「测试连接」做了什么
它拿一个不存在的支付单号去 Antom 查一次单 —— 不会产生任何真实动作， 但能一次验证四件事：网关区域对不对、Client ID 对不对、私钥对不对、沙箱开关对不对。 另外还会把「Antom 公钥」解析一遍，确认它至少是一把格式合法的公钥。
显示「连接成功（沙箱）」才算过。
「测试连接」唯一查不出来的事
它证明不了你填的是Antom 那把公钥 —— 因为你手上两把公钥的格式一模一样， 填哪把都能通过。
原因是：发请求只用私钥签名，公钥要等第一个回调才用得到。 填错的表现是「支付发起正常、买家也付了钱，但所有回调被判为伪造，订单一直停在待付款」。
所以保存之后一定要真的跑一单沙箱（下一节），那是唯一能验出这一格的办法。
会要求输入验证器的 6 位数字
改支付通道要过手机验证器（TOTP），这是全站唯一需要二次验证的地方。 详见 支付通道总览。
第 4 步：跑一单沙箱
- 在 C 端下一单，结算时选 Alipay+
- 会整页跳到 Antom 的收银台，上面列着各个钱包
- 按 Antom 沙箱的说明完成支付（沙箱的钱包会直接放行）
- 跳回你的站点，支付结果页会自己轮询
跳回来时显示"处理中"是正常的
回调是异步的，你跳回来的时候它可能还没到。页面会自己轮询， 别把这一刻的"处理中"当成失败。
如果十几秒后还是待付款，去后台 → 订单 → 那一单，看看回调有没有到。
第 5 步：换成正式
沙箱跑通之后：
- 先让 Antom 把你的商家账户激活（集成引导第 4 步「切换至生产模式」在那之前是灰的）
- 切到生产模式后，控制台会给你一套新的 Client ID / 密钥（不带
SANDBOX_前缀） - 后台把通道的环境开关改成 正式
- 四个值全部重填一遍
切换环境时密钥框会被清空，这是故意的
不清空的话，框里显示的是掩码（看着像填好了），实际还握着沙箱的密钥 —— 通道标着「正式」却连的是沙箱，每一笔真实付款的回调都会失败。
看到框空了不要慌，重填就是。
上线前别忘了停用沙箱通道
python deploy/deploy.py check 会检查这一项并报警。
出问题时对照这张表
大部分错误系统会直接告诉你该改哪一格，照着提示改就行。下面这张表只列 「提示本身不够明显」或者「根本不报错」的情况：
| 提示 / 现象 | 怎么办 |
|---|---|
| 「你填的是一把公钥（长 392…）。私钥要长得多——约 1600 字符、MIIE 开头」 | 「商户私钥」填成公钥了，换成那段 1628 字符的 |
| 「你填的是一把私钥。这一格要的是 Antom 给你的公钥，约 392 字符、MIIBIj 开头」 | 两格填反了，对调 |
| 「这是 PKCS#1 格式（BEGIN RSA PRIVATE KEY），要先转成 PKCS#8」 | 照提示里那条 openssl pkcs8 -topk8 命令转一下 |
「通道设为沙箱，但 Client ID 不是 SANDBOX_ 开头」 | 沙箱/正式的凭据拿混了，按提示改一边 |
「Antom 拒绝了这次请求：SIGNATURE_INVALID…」 | 密钥格式是对的但签名不被接受 —— 八成是网关区域选错了 |
「Antom 拒绝了这次请求：ACCESS_DENIED / CLIENT_INVALID」 | Client ID 和这把私钥不是一对，或者该产品还没开通 |
| 「无法连接支付服务，请稍后重试」 | 这个现在只代表真的网络不通（服务器出不去网、网关地址拼错） |
| 发起支付报「Antom 没有返回收银台地址」 | Antom 那边这个币种或产品没开通，看控制台的开通状态 |
| ★ 支付发起正常、买家也付了钱，但订单一直停在「待付款」 | 两种可能：①「Antom 公钥」填成了你自己那把（最常见，测试连接查不出来）；② 站点设置里的域名没填或填错 —— 回调地址是用它拼的 |
退款报「Antom 退款被拒：XXX …」 | 括号里就是 Antom 的原话，按它说的改 |
| Antom 一直重复推送同一条通知 | 正常情况下不会发生。真遇到就是我们回给它的应答格式不对，找技术 |
日志在哪
回调的处理结果记在服务器的 /opt/mall/logs/mall.log 里，搜 支付回调处理完成。 被判为伪造的会记成 支付回调被拒。
退款
和其它通道一样，走售后工单，不用去 Antom 后台操作。
Antom 的退款是异步的
点了退款之后，后台可能先显示「处理中」，钱实际到账要等 Antom 的结果通知。 Stripe / PayPal 是当场就有结论的，这一点不一样，别以为卡住了。
在 Antom 后台怎么和我们的单子对上
控制台的请求日志里，退款那一条的 refundRequestId 就是后台的退款单号 （形如 R202609050206492057），一一对应，不用另找线索。
支付那一条同理：paymentRequestId 就是我们的支付单号（P2026…）， 而 paymentId 是 Antom 自己的流水号。
常见问题
问：接了 Antom 还要不要留 Stripe？ 要。Antom 覆盖的是钱包，欧美买家的信用卡还是走 Stripe。三个通道可以同时开着， 买家在结算页自己选。
问：Antom 的手续费多少？ 按国家和支付方式分档，以你和 Antom 签的合同为准，系统不参与这件事。
问：结算币种怎么算？ 用你在 Antom 那边配的结算币种，系统按订单自己的币种发起收款，不做任何汇率换算。