- 集成指南
- 支持的功能（付款操作）
- 子网关商家
子网关商家
子网关可以直接使用网关，不需要在网关中为每个商家（客户端商家）设置商家配置文件。
如果您在网关中的商家配置文件配置为子网关商家配置文件，您可以在 API 请求中提交处理请求所需的商家配置详细信息。
- API 版本 53 及更高版本支持子网关商家功能，仅在 API 身份验证 API 请求中支持。
- 客户端商家的配置详细信息只需要在 Initiate Authentication 请求中提供 — 网关会自动将这些详细信息应用于 Initiate Authentication 和 Authenticate Payer 操作。
- 如果您的商家配置文件配置为子网关商家配置文件，在不提供子网关商家详细信息的情况下，您将无法提交交易进行处理。
- 子网关商家功能不提供对整合方（也称为支付服务商）的支持，即它不允许您代表其他商家（子商家）提交交易。 有关网关整合方功能的详细信息，请参阅整合方支持。
先决条件
Your payment service provider 必须在您在网关中的商家配置文件上启用子网关商家功能。
提交 3DS 交易
在子网关商家配置文件上使用身份验证 API 时，您必须在 Initiate Authentication 请求中为您的客户端商家提供以下详细信息：
- 客户端商家详细信息，包括 ID、名称、网站 URL 和地址
- 商家收单行链接详细信息，包括客户端商家的收单行商家 ID
- 您的客户端商家的 3DS 配置详细信息
此外，您还必须在 Authenticate Payer 请求中提供交易频率。
网关确定是否应执行 3DS2 或 3DS1（包括回退到 3DS1）的规则对于子网关商家和任何其他商家都是相同的。 参见 3DS 支付验证了解详细信息。
Initiate Authentication API 参考 [REST] [NVP]
Authenticate Payer API 参考 [REST] [NVP]
客户端商家详细信息
您必须在 Initiate Authentication 请求中提供您的客户端商家的以下详细信息：
subgatewayMerchant.id: 您的客户端商家的标识符，即您为其提交请求的商家。subgatewayMerchant.name: 客户端商家名称。subgatewayMerchant.websiteUrl: 客户端商家的网站 URL。subgatewayMerchant.address.*: 客户端商家的地址详细信息。order.merchantCategoryCode: 客户端商家的商家类别代码（用于根据企业提供的商品或服务类型对企业进行分类的 4 位数代码）。
商家收单行链接详细信息
对于根据您的网关商家配置文件配置的每个收单行（客户端商家可以为其处理交易），您必须在 Initiate Authentication 请求中提供客户端商家的收单行商家 ID：
subgatewayMerchant.acquirer[n].id: 您在为其提供客户端商家的收单行商家 ID 的收单行的网关收单行 ID。subgatewayMerchant.acquirer[n].acquirerMerchantId: 此收单行的客户端收单行商家 ID。subgatewayMerchant.acquirer[n].merchantCategoryCode: 此收单行的客户端商家的商家类别代码。 仅当此收单行需要与您可能指定的其他收单行链接不同的 MCC 值时，您才需要提供此值。 如果所有收单行都适用相同的 MCC，只需使用order.merchantCategoryCode如果您在请求中提供了subgatewayMerchant.authentication[n].acquirerBIN，不要提供此字段。
网关将仅处理您已为被识别为用于处理请求的收单行的收单行提供客户端收单行商家 ID 的请求（基于网关做出的交易路由决定，即识别的商家收单行链接）。
您只能提交 your payment service provider 已为您配置的收单行商家 ID。 如果您提交了还未进行配置的值，请联系 your payment service provider。
3DS2 详细信息
您必须在 Initiate Authentication 请求中为您的客户端商家提供 3DS2 配置详细信息，包括：
subgatewayMerchant.authentication[n].protocol: 客户端商家可以为其执行 3DS2 付款人身份验证的身份验证计划。subgatewayMerchant.authentication[n].3DS2.requestorId仅 American Express SafeKey 需要。subgatewayMerchant.authentication[n].3DS2.requestorName（可选）仅 需要。
Mastercard SecureCode 和 Verified By Visa 仅要求通过 subgatewayMerchant.authentication[n].protocol 字段识别身份验证计划。 请求者 ID 和请求者名称由网关生成。 网关生成（并提交给 MI 服务器）的值将在 Initiate Authentication 响应中返回。
对于 American Express SafeKey，您必须提供所有详细信息，包括请求者 ID 和请求者姓名。
网关将仅处理您在请求中提供了协议（以及请求者 ID 和请求者姓名(如果需要)）的请求。 例如，如果您提供的卡号被网关识别为 American Express 卡，但您未在请求中提供 subgatewayMerchant.authentication[n].protocol=AMEX_SAFEKEY，请求将被网关拒绝。
3DS1 详细信息
网关为 Mastercard SecureCode、Verified by Visa 和 American Express Safekey 提供 3DS1 支持。
您必须在 Initiate Authentication 请求中为您的客户端商家提供 3DS1 配置详细信息，包括：
subgatewayMerchant.acquirer[n].3DS1.masterCardSecureCode.merchantIdsubgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorIdsubgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalIdsubgatewayMerchant.acquirer[n].3DS1.amexSafeKey.merchantId
必须为每个收单行（由 subgatewayMerchant.acquirer[n] 标识）提供这些信息，以便客户端商家可以执行 3DS1 付款人身份验证。
收单行选择
如果 your payment service provider 为您配置了多个具有相同货币、卡类型和业务线组合的收单行链接，您需要使用 Initiate Authentication 请求中的 subgatewayMerchant.acquirer[n].id 字段识别您想要用于处理身份验证的收单行。
如果网关无法唯一识别出收单行，它将返回错误消息。
测试您的集成
要测试您的集成，您可以在生产环境中使用测试商家配置文件。 请参见测试与投入使用。