- 集成指南
- 支持的功能（付款操作）
- 整合方支持
整合方支持
Mastercard Gateway 为您担任整合方提供支持。 这让您可以向其他商家（称为下级商家）提供在线服务以便接受电子支付，此时下级商家不需要与收单行或网关建立合同关系。 此选项对于只有少量交易需要接受付款人在线付款的商家而言具有吸引力，并且设置起来非常快捷。
下级商家只需与您签订合同。 您管理与收单行的合同关系，接收下级商家资金并结算下级商家的资金。
- 整合方功能由 API 版本 32 及更高版本提供。
- 如果您希望担任整合方，需要遵守卡组织的某些要求。 有关详细信息，请联系您的收单行和/或卡组织。
- 除其他子商家详细信息外，American Express 还需要付款整合方的电子邮件和电话号码。
先决条件
您必须与收单行联系，对方会将您注册到卡组织以将您设置为整合方。 收单行可能向您发放整合方 ID 和/或名称。请将这些详细信息提供给 your payment service provider。
Your payment service provider 必须在网关中对您的商家配置文件进行相应设置（商家收单行链接）。
为下级商家提交 API 交易
通过以下 API 操作提交下级商家的交易时，您可以提供下方 order.subMerchant 参数组指示的下级商家详细信息。
API 请求：
PAYAUTHORIZE- Standalone
CAPTURE - Standalone
REFUND VERIFYUPDATE_SESSION
下级商家详细信息：
order.subMerchant.identifier（如果提供order.subMerchant.tradingName，则必须填写）order.subMerchant.registeredNameorder.subMerchant.tradingName（如果提供order.subMerchant.identifier，则必须填写）order.subMerchant.bankIndustryCodeorder.subMerchant.address.*字段order.subMerchant.phoneorder.subMerchant.email
如果提供，这些信息将在以下响应中返回：
RETRIEVE_TRANSACTIONRETRIEVE_ORDERRETRIEVE_SESSION
如果网关不为您的收单行提供整合方支持，包含下级商家详细信息的请求将被拒绝。
下级商家详细信息适用于订单中的所有交易。 这些信息只能在初始交易中提供，即创建订单的交易。 如果在后续交易中提供（即，现有订单的交易，类似于后续的 CAPTURE 或 REFUND 请求），网关将拒绝请求。
Tokenization
对于低于 70 的 API 版本，如果您担任整合方，可能无法使用 Tokenization 功能。 网关将拒绝启用了 Tokenization 的商家的包含下级商家详细信息的交易请求。
从 API 版本 70 开始，如果您担任整合方，可以使用 Tokenization 功能。 以下操作添加了对 Tokenization 功能的支持：
请求：
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
DELETE_TOKENSEARCH_TOKEN, andRETRIEVE_TOKEN.
响应：
TOKENIZECreate or Update TokenCreate or Update Token (system generated token)
TOKENIZE_BROWSER_PAYMENT, andRETRIEVE_TOKEN.
作为使用 Tokenization 功能的整合方，您必须在 subMerchant 参数组中提供以下下级商家详细信息。
subMerchantsubMerchant.identifier
作为整合方商家，您应该
- 在所有令牌化操作中提供下级商家标识符
- 在交易请求中提供下级商家详细信息
- 作为整合方启用，以及
- 使用支持整合方交易的收单行链接（必须在收单行链接中启用 aggregatorsupport 功能）。
限制
以下功能目前不可用：
- 不能为整合方配置“令牌生成策略 = 收单行”的库。
- 不能为整合方配置外部令牌库（tokenprovider = LTV 或 TV2G）。
- 不能为整合方配置网关令牌网络令牌化。
Hosted Checkout
如果您希望向下级商家提供 Hosted Checkout 功能，那么您必须为其提供用于与 Hosted Checkout 集成的界面。
如果您提供下级商家详细信息，在调用 Checkout.configure() 时您必须会话 ID。 提交 APICREATE_CHECKOUT_SESSION 请求，并包括下级商家订单详细信息以生成会话 ID。 付款人浏览器将被返回到您的应用程序，您必须将付款人重定向到下级商家应用程序。
请使用 Checkout.configure() 提供下级商家显示详细信息，如商家名称、地址、联系详细信息和徽标。 这些详细信息将在 Hosted Checkout 交互期间呈现给付款人。
请勿向下级商家提供您的网关凭据。 否则，他们将能够访问其他下级商家的交易。
EMV 3DS 支付验证
若要通过网关支持下级商家使用 EMV 3DS 支付验证 (3DS2)，整合方必须在 Initiate Authentication 请求中提交相关的下级商家详细信息。 当下级商家详细信息被提交到网关时，网关将在下游的身份验证消息中使用下级商家详细信息来代替整合方详细信息。 需要提供的字段因计划而异。 不支持的计划包括：
- Mastercard SecureCode™
- Verified by Visa
- American Express SafeKey
- mada secure
请联系您的支付服务提供商，了解他们支持哪个计划。
如果身份验证之后是使用引用 3DS2 身份验证 ID 的 Authorize 或 Pay 操作的付款，那么，在 Initiate Authentication 请求中提供的下级商家详细信息也会在 Authorize/Pay 操作中使用。
步骤 1： 发起身份验证
除了“集成指南”中发起身份验证部分列出的其他必需字段外，还应在 Initiate Authentication 请求中提供您的下级商家的以下详细信息。
要查看 Initiate Authentication 响应的关键响应字段，请参阅“集成指南”中的“发起身份验证”部分。
下级商家详细信息
order.subMerchant.identifier（所有支持的 3DS2 计划均必须提供）order.subMerchant.tradingName（所有支持的 3DS2 计划均必须提供）order.subMerchant.bankIndustryCode（所有支持的 3DS2 计划均必须提供）order.subMerchant.registeredNameorder.subMerchant.address.country（所有支持的 3DS2 计划均必须提供）order.subMerchant.address.*（其他地址字段）order.subMerchant.phoneorder.subMerchant.email
3DS2 详细信息
请为下级商家提供以下 3DS2 配置详细信息。 作为先决条件，您必须在您的商家配置文件中分别启用下级商家可以执行其 3DS2 付款人身份验证的 3DS2 身份验证计划。
order.subMerchant.websiteUrl: 下级商家的网站 URL。 如果未提供，将使用您的商家配置文件中的网站 URL。order.subMerchant.authentication[n].protocolorder.subMerchant.authentication[n].3DS2.requestorIdorder.subMerchant.authentication[n].3DS2.requestorName
对于 Mastercard SecureCode、JCB J/Secure 和 mada secure，请勿提供身份验证详细信息。 请求者 ID 和请求者名称由网关生成。
为 Verified by Visa 提供身份验证详细信息时，仅提供身份验证协议。 请求者 ID 和请求者名称由网关生成。
对于 American Express Safekey，网关将使用请求者 ID“AGG”，它代表整合方。 如果 American Express 有要求，您可以覆盖此值，使用其他值。 与其他计划一样，网关将创建请求者名称。
示例
Initiate Authentication 请求
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP 方法 | PUT |
{
"authentication": {
"acceptVersions":"3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION"
},
"correlationId": "test",
"order": {
"currency": "USD",
"subMerchant": {
"authentication":[
{
"protocol":"AMEX_SAFEKEY",
"3DS2":{
"requestorId":"testRequestorId",
"requestorName":"testRequestorName"
}
}
],
"identifier": "123456",
"tradingName": "SubmerchantName",
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"registeredName": "SubmerchantRegisteredName"
}
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174"
}
}
},
"apiOperation": "INITIATE_AUTHENTICATION"
}
Initiate Authentication 响应
{
"authentication":
{
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"acceptVersions": "3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customized": {
"3DS": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==",
"methodUrl": "https://qa06.gateway.mastercard.com/acs/mastercard/v2/method"
}
}
},
"redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\"> </iframe> <form id=\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA2LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS8xYjZjMmNiYTc3NjMxZDBjNTAxOWM1YzUxMzZmM2ZjZWI4NDZiMGE4ZTFkZmM2Njg2YjA1YWNkZjQxMGZkMWEwIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJmYzBmNDg0OC03MzQzLTQzMDAtOTg2YS05NmQwYmE0MDM0ODUifQ==\"/> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TESTMITSUKO_GWS",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:21:19.966Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:21:19.966Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
步骤 2： 对付款人进行身份验证
请参阅对付款人进行身份验证了解有关下级商家流的所有说明。
示例
Authenticate Payer 请求
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP 方法 | PUT |
{
"correlationId": "foo",
"order": {
"amount": "100",
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month" : "01",
"year" : "39"
}
}
}
},
"device": {
"browser": "MOZILLA",
"browserDetails": {
"3DSecureChallengeWindowSize": "FULL_SCREEN",
"acceptHeaders": "application/json",
"colorDepth": 24,
"javaEnabled": true,
"language": "en-US",
"screenHeight": 640,
"screenWidth": 480,
"timeZone": 273
},
"ipAddress": "127.0.0.1"
},
"apiOperation": "AUTHENTICATE_PAYER"
}
Authenticate Payer 响应 - 3DS2 无障碍流成功
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"3dsServerTransactionId": "fc0f4848-7343-4300-986a-96d0ba403485",
"acsTransactionId": "ebd1628f-b62a-44f6-bb2d-480359ac3e70",
"directoryServerId": "A999999999",
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.1.0",
"requestorId": "testRequestorId",
"requestorName": "testRequestorName",
"transactionStatus": "Y"
},
"payerInteraction": "NOT_REQUIRED",
"redirect": {
"customized": {
"3DS": {
"acsUrl": "https://qa06.gateway.mastercard.com/callbackInterface/gateway/3a672661a6b7027834df3e5863e78f02152c7b99b18b0f9ea8bbd30f86323dc2",
"cReq": "e30="
}
},
"domainName": "qa06.gateway.mastercard.com"
},
"redirectHtml":"<div id=\"threedsFrictionLessRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"challengeFrame\" name=\"challengeFrame\" </iframe> <form id=\"threedsFrictionLessRedirectForm\" method=\"POST\" action=\"https://qa06.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"order.id\" value=\"TEST1234\"/> <input type=\"hidden\" name=\"transaction.id\" value=\"123\"/> input type=\"hidden\" name=\"response.gatewayRecommendation\" value=\"PROCEED\"/> <input type=\"hidden\" name=\"result\" value=\"SUCCESS\"/> </form> <script id=\"authenticate-payer-script\"> </script> var e=document.getElementById(\"threedsFrictionLessRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"version": "3DS2"
},
"correlationId": "foo",
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"creationTime": "2022-03-03T02:21:20.043Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:25:30.340Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"authentication": [
{
"3DS2": {
"requestorId": "testRequestorId",
"requestorName": "testRequestorName"
},
"protocol": "AMEX_SAFEKEY"
}
],
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:25:30.340Z",
"timeOfRecord": "2022-03-03T02:21:20.043Z",
"transaction": {
"acquirer": {
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "USD",
"id": "123",
"type": "AUTHENTICATION"
},
"version": "64"
}
步骤 3： 在付款操作中使用身份验证结果
请参阅在付款操作中使用身份验证结果了解有关下级商家流的所有说明。
示例
Authorize 请求
| URL | https://mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "AUTHORIZE",
"authentication": {
"transactionId": "123"
},
"order": {
"amount": "100",
"currency": "USD",
"reference": "300"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "373224999999174",
"expiry": {
"month": "01",
"year": "39"
}
}
},
"type": "CARD"
},
"transaction": {
"source": "INTERNET",
"reference": "3600"
}
}
Authorize 响应
{
"authentication": {
"3ds": {
"acsEci": "05",
"authenticationToken": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId": "AgEAAJZvNBiNg0EWkd6ryLVH8ik="
},
"3ds2": {
"dsTransactionId": "966f3418-8d83-4116-91de-abc8b547f229",
"protocolVersion": "2.1.0",
"transactionStatus": "Y"
},
"transactionId": "123",
"version": "3DS2"
},
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"device": {
"browser": "MOZILLA",
"ipAddress": "127.0.0.1"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTMITSUKO_GWS",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2022-03-03T02:21:19.948Z",
"currency": "USD",
"id": "TEST1234",
"lastUpdatedTime": "2022-03-03T02:45:56.851Z",
"merchantAmount": 100.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "USD",
"reference": "300",
"status": "AUTHORIZED",
"subMerchant": {
"address": {
"city": "sydney",
"company": "Acme",
"country": "AUS"
},
"bankIndustryCode": "1234",
"identifier": "123456",
"registeredName": "SubmerchantRegisteredName",
"tradingName": "SubmerchantName"
},
"totalAuthorizedAmount": 100.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "000",
"acquirerMessage": "Approved ",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"issuer": "AMERICAN EXPRESS US CONSUMER",
"number": "373224xxxxx9174",
"scheme": "AMEX",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-03T02:45:56.851Z",
"timeOfRecord": "2022-03-03T02:45:56.762Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "AMEXGWS",
"merchantId": "1234567890"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"authorizationCode": "007257",
"currency": "USD",
"id": "1234",
"receipt": "2203031",
"reference": "3600",
"source": "INTERNET",
"stan": "1",
"terminal": "123456",
"type": "AUTHORIZATION"
},
"version": "64"
}