如何在Mastercard Gateway API中正确集成cofReason与mada交易类型？

背景 #

• 已完成Mastercard Gateway API（MPGS）REST直接集成，正常运行并测试以下API：
  • 创建会话
  • 更新会话（含卡片信息）
  • 发起3DS认证
  • 持卡人3DS认证
  • 发起支付交易
• 收到NPG API v2.2.1新文档，引入cofReason参数及Mada交易类型（如REGISTERED_INITIAL、RECURRING_INITIAL等）

疑问 #

1. 是否需要将这些新参数加入现有API流程？
2. 若需要，应在哪些具体API请求中携带cofReason和Mada交易值（如更新会话、发起认证或支付API）？
3. 还是需通过其他特定NPG API流程处理？

尝试操作及错误 #

曾在Update Session的order和sourceOfFunds字段中添加cofReason，收到错误：

{
    "error": {
        "cause": "INVALID_REQUEST",
        "explanation": "Unexpected parameter 'order.cofReason'"
    },
    "result": "ERROR"
}

需求 #

确保正确应用新要求，尤其是针对Mada卡及循环/COF交易场景。

环境信息 #

• API：Mastercard Gateway（REST直接集成）
• 参考文档：GitHub MPGS集成指南
• 新增参考：NPG API v2.2.1发布说明（Mada特定用例）

解答 #

1. 是否需要添加新参数？

如果你的业务涉及Mada卡的循环交易/COF（Card on File）场景（比如订阅、定期扣款、持卡人发起的重复交易等），则必须添加这些参数——这是NPG v2.2.1针对Mada地区合规要求新增的配置项，不配置可能导致Mada卡交易失败。若不涉及这类场景，可暂时不添加，但建议提前兼容以覆盖未来业务需求。

2. 正确的参数放置位置

cofReason和Mada交易类型参数不能放在Update Session接口，这就是你报错的原因。正确的位置是在**发起支付交易（Create Payment）或发起3DS认证（Create Authentication）**的请求体中，具体字段如下：

针对COF场景的参数结构示例（Create Payment请求）

{
  "apiOperation": "PAY",
  "order": {
    "id": "YOUR_ORDER_ID",
    "amount": "10.00",
    "currency": "SAR"
  },
  "sourceOfFunds": {
    "provided": {
      "card": {
        "number": "4111111111111111",
        "expiry": "12/25"
      }
    },
    "type": "CARD"
  },
  "cof": {
    "reason": "RECURRING_INITIAL", // 对应cofReason，可选值参考文档：REGISTERED_INITIAL、RECURRING_INITIAL、RECURRING、INSTANT
    "madaTransactionType": "RECURRING_INITIAL" // Mada特定交易类型，仅针对Mada卡
  }
}

关键说明：

• cof.reason：标识COF交易的类型，所有COF场景都需配置，不管是否是Mada卡
• cof.madaTransactionType：仅当持卡人使用Mada卡时必填，值需与cof.reason匹配（比如RECURRING_INITIAL对应RECURRING_INITIAL）
• 若使用3DS认证，需在Create Authentication请求中同样携带cof对象，确保认证环节与支付环节的参数一致

3. 是否需要特定API流程？

不需要额外的NPG API流程，只需在现有支付/认证流程中添加上述cof参数即可。但需注意：

• 对于首次注册COF的交易（比如REGISTERED_INITIAL），需确保持卡人明确授权存储卡片信息用于后续交易
• 重复交易（RECURRING）需基于首次成功的COF交易记录发起，可使用首次交易返回的session.id或order.id关联

补充排查建议 #

你之前在Update Session中添加参数报错，是因为该接口的schema未包含cofReason字段，所有COF相关参数都属于支付/认证请求的范畴，与会话更新无关。

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