你需要什么
| 字段 | 它做什么 |
|---|---|
| Access token | 让我们调用 Square 来创建结账链接。机密。 |
| Webhook signature key | 确认一个 webhook 确实来自 Square。机密。 |
| Location ID | 接收这笔款项的那个 Square 地点。它设定币种。 |
| 成功网址 / 取消网址 | 买家在付款或退出后落到哪里。 |
我们为什么要每个字段
Access token
授权创建结账链接，使扣款通过你的账户进行。
Webhook signature key
证明一个传入的 webhook 真的来自 Square，于是没人能伪造一个“已付款”事件。它是一个与 access token 不同的值。
Location ID
告诉 Square 哪个地点接收这笔钱，并设定结账币种。非机密。
成功与取消网址
普通设置：买家在付款或退出后落到哪里。非机密。
设置
- 打开 Square 开发者后台
在 developer.squareup.com 登录。每个应用都有自己的凭据，并随之创建一个免费沙盒用于测试。本指南演示沙盒流程；正式流程完全相同，只需切换"沙盒 / 生产"开关并使用你的生产凭据。要创建新应用，点击"应用"界面上的"+"方块。
Square Developer → Applications - 为你的应用命名
给应用取一个你能认出的名字（例如"Coin Moebius"），然后点击"下一步"。
Square → 为你的应用命名 - 复制你的 access token
打开应用并进入"Credentials"。确认顶部的"沙盒 / 生产"开关与你正在设置的环境一致。点击 Access token 旁边的复制图标并保存备用。
Square → Credentials access token 是机密的，请像对待密码一样保管它。沙盒和生产各有独立的 token，请勿混淆。
- 复制你的 Location ID
在左侧菜单中打开"Locations"。复制应当接收付款的那个地点的 Location ID。它决定结账币种，因此请选择你希望以其币种收款的地点。
Square → Locations - 打开 Webhooks → Subscriptions
Square 把 webhook 端点称为"subscription（订阅）"。在左侧菜单中展开"Webhooks"，打开"Subscriptions"，然后点击"添加订阅"。
Square → Webhooks → Subscriptions → 添加订阅 - 添加订阅并选择事件
给它取一个名字（例如"coin-moebius"）。在"Notification URL"中粘贴你项目的 Square webhook 地址（见下）。然后在"Events"下搜索并勾选 Coin Moebius 监听的事件，点击"保存"。
- 一次性付款：payment.created、payment.updated、refund.created、refund.updated、dispute.created、dispute.state.updated。
- 订阅（仅当你销售订阅时）：subscription.created、subscription.updated、subscription.canceled、subscription.deactivated、invoice.payment_made、invoice.scheduled_charge_failed。如果你不按周期计费，请跳过这些。
https://api.coinmoebius.com/webhook/square/<your project id>Square → 添加 webhook 订阅 你的项目 ID 显示在 Coin Moebius 后台的项目名称下方；将其填入上方地址中。多选事件无害，我们会忽略用不到的。已连接的渠道卡片（最后一步）也会显示同一个 URL 供参考。
- 打开刚才创建的订阅
Square 保存订阅并将其列在"Webhooks"下，状态为"已启用"。点击其名称打开详情面板，签名密钥就在其中。
Square → Webhooks → 你的订阅（已启用） - 复制 Signature key
在订阅的"Properties"面板中，点击 Signature key 旁边的复制图标。这是 Coin Moebius 用于确认每个 webhook 确实来自 Square 的值。它只在订阅创建后才存在，这就是为什么 webhook 步骤在连接步骤之前。
Square → 你的订阅 → Signature key - 回到 Coin Moebius：添加渠道 → Square
在你的项目里，打开"渠道"标签，点击"添加渠道"，选择"连接服务"，然后选择 Square。设置你的成功网址和取消网址。在"正式"标签页，粘贴你的 Access token、Webhook signature key 和 Location ID，然后点击"保存"。先用沙盒凭据设置？改为将它们粘贴到"测试"标签页，之后再通过"编辑"添加正式凭据。
Coin Moebius → 添加渠道 → Square - 连接完成
Square 现在出现在你的"渠道"标签上，显示连接日期。卡片上显示你粘贴到 Square 的同一个 webhook URL，以及"编辑"和"断开连接"按钮。使用"测试模式"开关在正式上线前端到端跑一次沙盒订单。
Coin Moebius → 渠道 → Square（已连接） 沙盒卡永远不会扣真卡。使用卡号 4111 1111 1111 1111，CVV 111，任意未来有效期，任意有效邮编（例如 94103）。
连接之后
上线前跑一笔测试付款：
- 创建一个商品，并把它的环境设为 Testing。这会让该商品跑在你的沙盒凭据上，于是你可以下一整单而不动真钱。（如果你跳过了沙盒组，一个 Testing 商品会回退到正式，所以请先添加它。）
- 把买按钮放到一个页面上（本地 HTML 文件也行），指向你的项目。
- 用上面的沙盒测试卡完成结账。
- 打开“交易”标签。一行带 Testing 标签的新行出现。当它的状态到达 succeeded 时，你的凭据和 webhook 就都端到端工作了。
准备好接收真实付款时，把商品环境切换到 Live。
问题排查
从“验证”开始。在后台里，点击“验证”（或“验证测试凭据”）来核对你的 access token 和地点。
验证失败。
重新复制 access token 和 Location ID。Production 和 Sandbox 有各自独立的 token，所以别把它们混了。
签名校验失败，或订单仍停在待处理。
Square 对确切的通知 URL 加上正文进行签名。你在 Square 里注册的 URL 必须与你的 webhook URL 逐字一致，不带尾部斜杠，也不带额外的查询字符串。然后从同一个端点重新复制 signature key。
端到端确认一下。
Square Developer Console → Webhooks → your subscription → Send Test Event，然后看着订单更新。
值得了解
币种跟随地点. 结账以你所提供 id 的那个地点的币种扣款。
轮换密钥. 随时滚动 access token 或 signature key，然后粘上新值。编辑时机密字段保持空白。
有问题？ Join our Discord