PAYATHON 2026

如何在 Drupal Commerce 中配置 payment gateway？

支付阿杰

结论

Drupal Commerce 提供支付流程和 payment gateway 插件框架，但不会自动接入具体的支付渠道。你需要安装与 Drupal Commerce 主版本兼容的支付模块，然后在后台创建支付网关，填写商户凭据，配置回调并在测试环境中完成验证。

在 Drupal Commerce 2.x 中，支付网关通常位于：

Commerce > Configuration > Payment gateways

对应的常见路径是：

/admin/commerce/config/payment-gateways

如果后台找不到这个入口，可能是支付相关模块尚未启用、支付插件尚未安装，或者当前账号没有所需权限。

配置步骤

1. 确认 Drupal Commerce 版本

先确认项目使用的是 Commerce 2.x，还是较早的 Commerce 1.x。两者使用不同的模块、后台界面和配置方式，支付模块不能混用。

Commerce 2.x 项目通常使用 Composer 管理依赖，可以运行：

composer show drupal/commerce

选择支付模块时，需要确认它兼容项目当前使用的 Drupal、Commerce 和 PHP 版本。具体安装命令应以该模块的项目说明为准，不要直接套用其他支付模块的包名。

2. 安装支付服务商模块

Drupal Commerce 核心负责订单、Payment 实体和结账流程。银行卡、PayPal、Stripe 等实际支付能力由单独的模块提供。

安装模块后，还需要启用该模块及其依赖。例如：

drush en MODULE_NAME -y
drush cr

将 MODULE_NAME 替换成实际的模块名称。启用后，打开支付网关管理页面，点击“添加支付网关”，检查是否已经出现相应的插件类型。

选择模块时，需要确认以下事项：

  • 是否明确支持当前的 Commerce 主版本；
  • 是否支持需要使用的国家、币种和支付方式；
  • 是否支持退款、预授权和后续扣款；
  • 采用站内支付还是跳转支付；
  • 是否支持 webhook 或异步通知；
  • 模块是否仍在维护，安装说明是否清楚。

3. 创建 payment gateway

打开：

/admin/commerce/config/payment-gateways

点击“添加支付网关”，选择已经安装的支付插件，然后填写网关名称、插件类型、运行模式、商户凭据和适用条件等信息。常见配置包括：

  • 网关名称；
  • 插件类型；
  • 测试或生产模式；
  • Merchant ID、API key、Client ID、Secret 等凭据；
  • 支持的支付操作；
  • 适用的商店、币种或订单金额等条件。

每个模块提供的字段可能不同，具体应以支付服务商后台和模块文档为准。

首次配置建议先使用测试模式，不要直接用真实银行卡，也不要在生产环境中反复试单。

4. 选择支付操作方式

支付网关通常支持以下一种或多种操作：

  • Authorize：只做预授权，不立即扣款；
  • Capture：扣取已经授权的金额；
  • Authorize and capture：下单时直接完成授权和扣款；
  • Void：撤销尚未捕获的授权；
  • Refund：退还已经完成的付款。

如果商品需要在发货前审核，可以先授权，发货时再捕获款项。数字商品或即时交付业务通常会直接授权并扣款。具体采用哪种方式，还要看支付渠道是否支持以及商户账户如何设置。

5. 检查结账流程

在 Commerce 的 checkout flow 配置中，确认流程包含支付步骤，并检查当前商店或订单是否能匹配刚创建的支付网关。

如果前台没有显示支付方式，可以依次检查：

  • 网关是否已经启用；
  • 网关是否处于测试模式却使用了生产凭据，或者处于生产模式却使用了测试凭据；
  • 当前订单的币种是否受支持；
  • 网关条件是否排除了当前商店或订单；
  • checkout flow 是否包含支付步骤；
  • 订单金额是否为零；
  • 当前用户角色是否具有必要权限。

6. 配置回调和 webhook

跳转支付和异步支付通常要求在支付服务商后台登记返回地址或 webhook 地址。具体 URL 应从已安装模块的配置页面或使用说明中获取，不要自行猜测。

配置后还要检查：

  • 站点能否通过公网 HTTPS 访问；
  • 支付服务商能否访问 webhook；
  • 反向代理、防火墙或安全模块是否拦截了回调；
  • webhook 签名或密钥是否配置正确；
  • 回调失败时，系统是否会误将订单标记为已付款。

浏览器跳转到“支付成功”页面，不代表服务器已经确认收款。订单的付款状态应以支付网关响应或通过签名验证的 webhook 为准。

凭据管理示例

有些支付模块允许从环境变量中读取密钥。如果模块只提供后台输入框，就应按照该模块规定的方式配置，不要假设所有插件都支持下面的写法。

对于自定义集成或支持配置覆盖的模块，可以在 settings.php 中读取环境变量：

$payment_api_key = getenv('PAYMENT_API_KEY');

if ($payment_api_key !== false) {
  $settings['payment_api_key'] = $payment_api_key;
}

在服务器环境中设置：

export PAYMENT_API_KEY='your-secret-key'

实际使用的配置键由支付模块决定。不要将生产密钥提交到 Git，同时要检查导出的 Drupal 配置中是否包含敏感字段。

上线前检查

上线前至少要完成一次完整的测试交易，并覆盖以下环节：

  1. 创建订单并进入支付页面；
  2. 使用服务商提供的测试账号或测试卡完成支付；
  3. 确认 Commerce 中已经生成 Payment 实体；
  4. 核对支付状态、金额和币种；
  5. 检查订单是否进入预期状态；
  6. 测试支付失败、取消和重复提交；
  7. 确认 webhook 可以正常接收；
  8. 根据业务需要测试退款、撤销或捕获；
  9. 切换到生产模式后，再用一笔小额真实交易进行核对。

调试时可以查看 Drupal 日志：

/admin/reports/dblog

如果没有启用数据库日志，可以改查服务器日志、PHP 日志以及支付服务商后台的请求记录。

注意事项

  • 测试凭据和生产凭据通常不能混用。
  • 生产站点必须启用 HTTPS。
  • 不要在日志中记录银行卡号、CVV、完整 API 密钥等敏感信息。
  • 如果使用站内银行卡表单，应优先选择支付服务商提供的托管字段或令牌化组件，避免敏感卡片数据经过 Drupal 服务器。
  • 缓存、防火墙、CDN 和 Basic Auth 都可能阻止 webhook 访问。
  • 支付完成后，不要只依靠前端跳转来更新订单状态。
  • 升级模块前应先检查兼容性，并在测试环境中验证支付、退款和 webhook。
  • Commerce 1.x 的配置资料不适用于 Commerce 2.x。查阅指南时，应先确认对应的版本。

配置时，应优先参考所选支付模块的 Drupal 项目页面、模块自带文档，以及支付服务商提供的 API 和 webhook 文档。Drupal Commerce 负责统一支付流程，商户账号申请、可用币种、费率和生产环境审核则由具体的支付服务商负责。

备注：内容仅供参考。