Magento集成MasterCard支付服务：托管结账方式接入求助

Hey there! Let's walk through integrating MasterCard's Hosted Checkout into your Magento store step by step—since you already have your merchant ID and know you want the hosted flow, we can jump right into the actionable stuff.

1. 确认Magento版本兼容性 #

首先要核对你的Magento版本（现在大多是2.x版本，如果还在使用1.x，步骤会略有不同）。MasterCard的官方工具只适配特定版本的Magento，所以先确保你的站点版本在支持范围内再继续。

2. 收集必要的MasterCard网关凭证 #

你已经拿到了商户ID，但还需要从MasterCard商家后台获取另外两个关键信息：

• API用户名和API密码（一般在Settings > API Credentials菜单下）
• 确认你使用的是沙箱（测试）环境还是生产环境——两个环境的基础URL不同：沙箱为https://sandbox.mastercard.com，生产环境为https://mastercard.com

3. 使用官方MasterCard Magento扩展（推荐方式） #

最省心的方法是用Magento市场里的MasterCard官方扩展，不用自己从零搭建：

• 登录Magento后台，进入Stores > Configuration > Sales > Payment Methods
• 如果没看到MasterCard Hosted Checkout选项，先从Magento Marketplace安装对应扩展
• 启用该支付方式，填入你的商户ID、API用户名和密码
• 选择对应的环境（沙箱/生产），再调整其他配置：比如允许使用的国家、显示顺序、支付完成后的跳转URL等
• 保存配置后，通过SSH执行命令清理Magento缓存：

  bin/magento cache:flush
  

4. 手动集成（适用于自定义场景） #

如果官方扩展不符合你的定制需求（比如自定义结账流程），可以手动实现集成：

• 步骤1：创建一个自定义Magento支付模块，并将其注册为站点的合法支付方式
• 步骤2：添加逻辑调用MasterCard API生成结账会话。以下是Magento 2.x环境下使用Guzzle的简化示例：

  $client = new \GuzzleHttp\Client();
  $merchantId = '你的商户ID';
  $apiUser = '你的API用户名';
  $apiPass = '你的API密码';
  
  $response = $client->post(
      "https://sandbox.mastercard.com/checkout/api/version/72/merchant/{$merchantId}/session",
      [
          'headers' => [
              'Content-Type' => 'application/json',
              'Authorization' => 'Basic ' . base64_encode("{$apiUser}:{$apiPass}")
          ],
          'json' => [
              'apiOperation' => 'CREATE_CHECKOUT_SESSION',
              'order' => [
                  'amount' => $order->getGrandTotal(),
                  'currency' => $order->getOrderCurrencyCode(),
                  'id' => $order->getIncrementId()
              ],
              'interaction' => [
                  'operation' => 'PURCHASE',
                  'returnUrl' => $this->_urlBuilder->getUrl('checkout/onepage/success'),
                  'cancelUrl' => $this->_urlBuilder->getUrl('checkout/onepage/failure')
              ]
          ]
      ]
  );
  
  $sessionData = json_decode($response->getBody()->getContents(), true);
  // 将session ID传递到前端模板
  

• 步骤3：前端拿到session ID后，引导用户跳转到MasterCard的托管结账页面：https://sandbox.mastercard.com/checkout/pay/{SESSION_ID}
• 步骤4：在Magento中创建一个webhook端点，处理MasterCard发送的支付状态回调，根据回调数据更新订单状态（成功/失败）

5. 完整流程测试 #

• 使用MasterCard提供的测试卡号（比如5555555555554444，过期日期填未来任意日期，CVV填123）在沙箱环境测试整个支付流程
• 验证订单状态是否正确更新、跳转是否正常、支付失败时是否有清晰的提示信息

6. 需要避开的常见坑点 #

• 确保你的Magento站点使用HTTPS——MasterCard要求所有支付相关的请求必须是加密连接
• 不要混淆沙箱和生产环境的凭证，所有测试完成后再切换到生产环境
• 确保webhook URL可以被MasterCard服务器访问到，不要被防火墙或CDN拦截
• 核对订单货币类型与MasterCard网关配置的货币一致

内容的提问来源于stack exchange，提问作者NAJEEB