易支付对接 GoCardless Direct Debit 支付收款插件，多币种自动扣款教程

做跨境业务、SaaS、订阅服务的时候，很多人会遇到一个现实问题：
国内用户习惯支付宝 / 微信，欧美用户更习惯银行代扣（Direct Debit）、ACH、SEPA，想一次性搞定很难。

GoCardless 是一家专注于「银行直接借记（Direct Debit）」的全球收款平台，可以帮你从用户的银行账户中按周期自动扣款，支持多个国家和地区的本地扣款通道，包括：

• 英国 Bacs 直接借记（GBP）

• 欧洲 SEPA 直接借记（EUR）

• 美国 ACH 借记（USD）

• 澳大利亚 BECS、瑞典 Autogiro、丹麦 Betalingsservice、加拿大 PAD 等

官方还给出了各币种的限制，例如 USD/ACH 至少 2 美元一笔，GBP/Bacs 至少 1 英镑一笔，EUR/SEPA 至少 1 欧元一笔。

本文就以 彩虹易支付 + GoCardless 支付插件 为例，演示如何在你现有的易支付平台中，对接 GoCardless，打通：

• 对欧美用户：使用银行卡信息发起 本地 Direct Debit（ACH / Bacs / SEPA）

• 支持 USD / GBP / EUR 多币种代扣

• 通过 Webhook 自动同步支付状态，配合彩虹易支付完成订单自动回调

如果你已经在用彩虹易支付做聚合支付，只要增加一个 GoCardless 插件和对应通道，就能“原地扩展”到欧美主流的银行代扣场景。

一、准备工作

在动手之前，建议先准备好以下几样东西：

1. 一套可正常使用的彩虹易支付源码，如果没有可以到https://www.wxcydz.cc/t-2893-1-1.html 购买下载。

   • PHP 环境、数据库正常

   • 商户添加、订单创建、其他支付接口正常

   • 有服务器管理权限（宝塔 / SFTP / SSH 均可）

2. GoCardless 商户账号

   • 在 GoCardless 官网注册账号，开通 Sandbox（沙盒）环境 用于测试

   • 完成基本的商户信息、公司/主体资料填报

   • 后台可以看到 Access Token（访问令牌） 和 Webhooks（回调端点） 配置页面

3. GoCardless 对接彩虹易支付的插件文件，如果没有可以到https://www.wxcydz.cc/t-2893-1-1.html 购买下载。

   • 插件一般包含以下目录结构（示意）：

     • /plugins/gocardless/gocardless_plugin.php

     • /plugins/gocardless/inc/GoCardlessClient.php

     • 可能附带图标、说明文档等

   • 如果是你自己开发 / 购买的插件，按插件说明为准

4. HTTPS 证书

   • 建议站点启用 HTTPS，以便 GoCardless Webhook 能正常访问你的回调 URL（多数生产环境会要求 https）

二、安装彩虹易支付 GoCardless 插件

1. 上传插件文件

1. 使用 SFTP / 宝塔面板进入你易支付网站的插件目录，例如：

   /www/wwwroot/pay.example.com/plugins

   

2. 把你拿到的 GoCardless 插件压缩包解压：

   • 插件是已经按照易支付结构打包好的，解压后会自动把文件放入 /plugins/gocardless/ 目录

2. 添加支付图标（可选）

为了在易支付前端展示更直观，你可以准备一个 GoCardless 图标，例如：

• 主图标：

  gocardless.ico

  可以点击下载图标

放到：

/易支付根目录/assets/icon/

然后在支付方式配置里引用这个图标，让前台支付通道列表看起来更美观。

3. 刷新插件列表

登录彩虹易支付后台（管理员账户）：

1. 找到 “支付插件 / 插件管理” 之类的菜单项

2. 点击「刷新插件 / 更新插件列表」

3. 正常情况下，你会看到类似：

GoCardless Direct Debit 支付插件
支持 USD / GBP / EUR 银行代扣

说明插件已经被系统识别。

三、在 GoCardless 后台获取必要参数

要让易支付成功调用 GoCardless，需要在 GoCardless 后台准备以下信息：

1. Access Token（访问令牌）

   在 GoCardless 后台：

   • 进入 Developers → API keys / Access tokens 页面

   • 生成一条 Sandbox access token（用于测试），形如：sandbox_xxxxxxxxx

   • 后面正式上线时再生成 Live access token（形如：live_xxxxxxxxx）

2. Webhook Endpoint & Secret

   GoCardless 会通过 webhooks 把付款结果、扣款失败、退款等事件实时推送给你的系统。官方推荐所有集成都使用 webhook 跟进状态变化。

   基本流程是：

   • 进入 GoCardless Dashboard 的 Developers → Webhooks（或 Webhook endpoints）页面

   • 点击「Add endpoint / Create webhook endpoint」

   • 在 URL 处填入你的易支付 Webhook 地址（下面第四节会讲）

   • 填写一个 Secret（自定义一串随机字符串）

   • 勾选你想接收的事件类型（建议先全选，调通后再精简）

   成功后，你会在 Webhook 列表中看到刚创建的 endpoint，同时可以查看/复制对应的 Secret —— 这串 Secret 要填回彩虹易支付插件配置中，用来校验签名。

   

四、在彩虹易支付后台新增支付方式

让易支付「认识」 GoCardless 这种支付类型，首先需要在后台新增一个支付方式（或者你用现有的类型也可以，这里给一个常见写法）：

1. 登录易支付后台

2. 找到「支付方式管理 / 支付类型管理」

3. 点击「新增支付方式」，示例：

• 显示名称：银行代扣（GoCardless）

• 调用值（英文标识）：gocardless

• 支持设备：PC + Mobile

• 图标：选刚才上传的 gocardless.ico

调用值要和插件内部的 $info['types'] 定义一致，插件会根据这个值判断是否走 GoCardless 通道。

如果你想区分地区，也可以新建多种方式，例如：

• gocardless_us（美国 ACH）

• gocardless_uk（英国 Bacs）

• gocardless_eu（欧洲 SEPA）

再在插件里根据类型做更细的逻辑，这里就按「统一一个 gocardless」来讲。

五、在彩虹易支付新增 GoCardless 支付通道

支付方式只是展示用的「壳」，真正决定收款的是「支付通道」。

1. 新增通道（基础配置）

在易支付后台：

1. 进入「支付接口 / 支付通道管理」

2. 点击「新增支付通道」，参考配置：

• 通道名称：GoCardless Direct Debit

• 支付方式：选择刚刚创建的「银行代扣（GoCardless）」

• 支付插件：选择 gocardless（插件刷新后出现的名称）

• 分成比例：按自身业务需求设置

• 状态：启用

2. 填写 GoCardless 插件配置项

不同版本插件字段名字可能略有差异，下面以常见字段为例说明含义（可根据你实际插件字段对应一下）：

• Live Access Token / 正式环境令牌：
  填你在 GoCardless Live 环境创建的 live_... 访问令牌；

• Sandbox Access Token / 沙盒令牌：
  填 sandbox_... 访问令牌（测试用）；

• 模式选择：

  • Sandbox（沙盒） → 所有订单都是模拟扣款，不动真钱

  • Live（正式） → 实际从用户银行发起代扣

• Webhook Secret：
  填你在 GoCardless Webhook Endpoint 设置的那串 Secret，用于 HMAC 校验；

• 汇率设置（如果插件内支持 CNY → USD/GBP/EUR 换算）：

  • 人民币→美元汇率 rate_usd：例如 1 CNY ≈ 0.14 USD，则填 0.14

  • 人民币→英镑汇率 rate_gbp：例如 1 CNY ≈ 0.11 GBP，则填 0.11

  • 人民币→欧元汇率 rate_eur：例如 1 CNY ≈ 0.13 EUR，则填 0.13

插件一般会在下单时：

• 取订单的基础金额（通常是 CNY）

• 根据用户的银行账户币种（USD / GBP / EUR）选择对应汇率

• 换算后传给 GoCardless，以最小货币单位（分/便士/分）提交。

3. 正确填写 Webhook 回调地址

在 GoCardless Webhook Endpoint 里，URL 必须带上通道 ID，形式为：

https://你的易支付域名/pay/webhook/通道ID/

例如：

https://pay.example.com/pay/webhook/5/

其中5就是你在易支付后台这个 GoCardless 通道的 ID（通道列表里通常会显示数字 ID）。

如果漏掉通道 ID，比如只写

https://pay.example.com/pay/webhook/

，插件是无法知道应该用哪个通道配置来验签和处理这条 Webhook 的。

填好 URL、Secret，保存。

六、关于 GoCardless 的币种、金额和到账时间

1. 最低支付金额限制

GoCardless 对不同币种/通道设置了最低金额限制，官方给出的（单位为对应货币本身）：

• USD / ACH：最低 2 USD

• GBP / Bacs：最低 1 GBP

• EUR / SEPA：最低 1 EUR

如果你这边换算后的金额低于这个值，就会收到 API 报错：

amount is lower than the minimum permitted amount

所以：

• 测试时建议订单至少 15~20 CNY 以上再换算

• 也可以在插件或前台做一个「最小金额校验」，避免用户支付 1 元被拒绝

2. Direct Debit 到账时间不是“秒到”

跟微信/支付宝不一样，GoCardless 的 Direct Debit 是“银行批量扣款”，流程大概是：

1. 你创建 Payment → 状态

   pending_submission

2. 到了扣款日（Charge date），GoCardless 提交给本地清算系统 →

   submitted

3. 银行确认扣款成功 →

   confirmed

4. 过几天钱结算到你的 GoCardless 账户/银行 →

   paid_out

整个过程通常要几天时间，因此：

• 用户不会立刻在银行 App 里看到扣款

• 也不要误以为「payment 创建成功 = 已经到钱」

比较严谨的做法是：

• 前端：下单返回成功页面时提示「代扣指令已提交，等待银行扣款」

• 后台：真正把订单改成“已支付”，最好还是根据 Webhook 收到的

  confirmed / paid_out

  状态来判断。

七、测试支付与回调（完整流程）

当你完成前面步骤后，建议按下面流程做一次完整测试（推荐先在 Sandbox 模式 测）：

1. 在你的前端站点发起一笔测试订单

   • 金额建议不要太小（比如 20 CNY）

   • 选择支付方式：银行代扣（GoCardless）

   • 正常会跳转到 GoCardless 的托管页面，让用户录入银行信息

2. 在 GoCardless 页面绑定测试银行账户

   • 沙盒环境会提供测试银行信息

   • Live 环境则需要你真实的银行账户（谨慎操作）

3. 支付完成后跳回你的站点

   • 用户会看到类似「支付请求已提交」或「等待银行扣款」的页面

   • 如果你的插件设计为“创建 Payment 即视为成功”，这时订单状态可能已经变成“已支付”

4. 在 GoCardless Dashboard 查看 Payment 状态

   • 进入 Payments 列表

   • 找到刚才这笔，查看：

     • 金额（例如 2.10 USD）

     • Status：

       pending_submission / submitted / confirmed / paid_out

     • Metadata 中的

       order_id

       是否为你的易支付订单号

5. 验证 Webhook 回调是否正常

   • 在 GoCardless Dashboard 的某笔 Payment 详情页，一般可以看到关联的 Webhook 事件

   • 查看你的服务器是否成功返回 200 OK

   • 检查易支付订单：

     • 是否能在

       confirmed / paid_out

       时自动标记为“已支付”

     • 如插件有日志，查看是否有签名失败、找不到订单等错误

如果：

• GoCardless 后台显示 Payment 成功，但易支付没更新订单

  • 检查 Webhook URL 是否带通道 ID

  • 检查 Webhook Secret 是否一致

• 易支付显示成功，但 GoCardless Payment 实际失败

  • 检查你有没有在“创建 payment 即标记成功”逻辑里，忽略了失败的重试

八、常见问题（FAQ）

1. 为什么用户刚付完钱，银行 App 里还没看到扣款？

因为 GoCardless 用的是 Direct Debit（银行代扣），不是实时卡支付。
官方文档也说明，Direct Debit 通常需要多个工作日完成扣款和清算，资金会在 confirmed / paid_out 后才真正完成划转。

2. 用户中途中止扣款或退款，会怎样？

• 在扣款前，用户可能会通过银行/GoCardless 取消 mandate 或 stop payment；

• 扣款后，也可能通过银行发起 indemnity claim / chargeback，导致款项被退回；

• 这些情况 GoCardless 会通过 Webhook 推送

  failed / cancelled / charged_back

  等事件，你可以在插件里根据这些状态对订单进行“退款/关闭”处理。

3. 金额太小总报错 “amount is lower than the minimum permitted amount”？

检查：

• 是否是 USD / ACH 通道，金额 < 2 USD

• 是否是 GBP / Bacs 或 EUR / SEPA 通道，金额 < 1 GBP / 1 EUR

• 汇率配置是否合理（不要把 CNY → USD/GBP/EUR 的汇率填错）

可以在插件里做「最小金额判断」，提示用户把订单金额调大一点再支付。

4. 多币种怎么配置比较科学？

常见做法：

• 使用统一基础币种（例如 CNY），在插件里按银行账户币种自动换算为 USD / GBP / EUR；

• 对欧美用户，建议用 USD / EUR / GBP 结算；

• 对某些只开了部分 Direct Debit 通道的商户，只开通对应地区用户使用。

5. Sandbox 和 Live 环境会互相影响吗？

不会。Sandbox 是完全隔离的测试环境：

• 用

  sandbox_... Access token

• Webhook 也推到你配置的测试回调 URL

• 不会实际从银行扣款，所有交易都是模拟

Live 环境用

live_... Token

，一定要确认：

• Webhook URL 填的是正式域名

• Secret 与生产 endpoint 一致

• 在正式上线前先用几笔小金额、自己或熟人账号做实测

总结

通过 彩虹易支付 + GoCardless Direct Debit 插件 的组合，你可以在不大改现有支付架构的前提下，得到：

• 覆盖欧美主流的银行代扣方式（ACH / Bacs / SEPA 等）

• 支持 USD / GBP / EUR 多币种自动扣款

• 通过 Webhook 与易支付订单系统自动同步支付状态

• 更适合订阅、周期扣款、SaaS 按月收费等场景

如果你已经在用彩虹易支付做国内聚合收款，只需：

1. 配置一个 GoCardless 插件、

2. 新增一条 GoCardless 支付通道、

3. 在 GoCardless 后台配置好 Access Token 和 Webhook，

就能从“只做国内支付”升级为「同时支持欧美银行代扣」的多通道收款平台。