- 集成指南
- 支持的功能（付款方式）
- 实施浏览器付款集成
- PayPal 支付
- 账单协议和定期付款
账单协议和定期付款
使用“使用 PayPal 结账”或“使用 PayPal 付款”，您可以为付款人设置账单协议，这允许您根据此账单协议发起参考交易（订阅/重复或按需付款），而无需付款人额外同意。 付款人登录 PayPal 一次来同意协议。 在账单协议通过审批后，付款人不需要登录 PayPal 来确认后续的付款。
有或无首次付款的 PayPal 账单协议流程
作为先决条件，您需要联系 PayPal 启用此功能来处理账单协议和参考交易。
此结账流如下所示︰
- 付款人浏览您的购物网站，选择产品，然后点击结账页的 PayPal。
- 当付款人单击 PayPal 按钮时，您对网关执行
Tokenize Browser Payment调用，并将付款人重定向到响应中返回的 PayPal URL。 请参见启动账单协议。 - 网关将付款人重定向到 PayPal 网站来审批协议详细信息。
- 付款人使用 PayPal 登录页登录到其 PayPal 账户。
- 付款人通过单击 PayPal 网站上的“同意并继续”或“同意并付款”按钮审查账单协议详细信息并确认详细信息。
- PayPal 将付款人重定向到对 PayPal 发起调用以执行账单协议的网关。 PayPal 返回协议 ID，网关将此 ID 作为令牌与其他协议详细信息一并存储。 请参见检索账单协议详细信息。
- 付款人浏览器返回到您的网站，在网站上，根据协议确认同意并付款或同意并继续，您将分别在当时根据账单协议发起付款或在将来按需进行。 请参见根据账单协议发起付款。
步骤 1： 创建会话
第一步是通过从 Web 服务器向网关提交 Create Session 请求来创建会话。 此操作将返回一个会话 ID，您可以用来引用此会话。
Create Session API 参考[REST][NVP]
步骤 2： 启动账单协议
在 Tokenize Browser Payment 请求中提供以下字段来启动账单协议并自定义 PayPal 提供的付款人体验。
token: 您希望创建或更新的令牌。 协议详细信息按此令牌存储。
仅当您配置了“商家提供”令牌生成策略时，才需要提供此字段。 否则，网关会为您创建令牌。sourceOfFunds.type = PAYPALsession.id: 将使用包含协议详细信息的令牌更新的付款会话的识别码（在步骤 1 中返回）。sourceOfFunds.provided.paypal.billingAgreement.description: 您的 PayPal 账单协议的描述。 当要求付款人审批账单协议时，会向他们显示此描述。sourceOfFunds.provided.paypal.billingAgreement.name: 您的 PayPal 账单协议的名称。sourceOfFunds.provided.paypal.billingAgreement.cardinality: 指示您与此付款人之间的账单协议的数量。 您可以将此项设置为：
MULTIPLE: 指示您与此付款人之间有多个账单协议。 这意味着将在每个请求的响应中返回新协议。SINGLE: 指示您与此付款人之间有一个账单协议。 这意味着将在每个请求的响应中返回相同协议。
browserPayment.returnUrl: 您希望在 PayPal 审批账单协议后付款人浏览器被重定向到的 URL。browserPayment.paypal.agreementConfirmation: 指示在付款人被重定向回您的网站前 PayPal 向付款人显示的操作。 您可以将此项设置为：
AGREE: 在 PayPal 网站上显示为“同意并继续”。 这意味着，在付款人审批了账单协议并且其浏览器返回了您的网站后，您不会在当时根据此账单协议处理付款。AGREE_AND_PAY: 在 PayPal 网站上显示为“同意并付款”。 这意味着，在付款人审批了账单协议并且其浏览器返回了您的网站后，您将根据此账单协议处理付款。
browserPayment.paypal.displayShippingAddress: 指示您是否希望 PayPal 在 PayPal 网站上向付款人显示送货地址。 您可以将此项设置为“true”或“false”。
默认情况下，向付款人显示送货地址。 有关详细信息，请参见显示/覆盖送货地址。browserPayment.paypal.overrideShippingAddress: 指示您是否希望允许付款人更改 PayPal 网站上付款的送货地址。 您可以将此项设置为“true”或“false”。
默认情况下，允许付款人更改送货地址。 有关详细信息，请参见显示/覆盖送货地址。
在提交此请求后，您必须将付款人的浏览器重新定向到 browserPayment.redirectUrl 字段中返回的 URL。
Tokenize Browser Payment API 参考 [REST][NVP]
以下是已使用“商家提供”的令牌生成策略生成令牌的 Tokenize Browser Payment 请求的示例。
| URL | https://mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId} |
| HTTP 方法 | POST |
{
"apiOperation": "TOKENIZE_BROWSER_PAYMENT",
"browserPayment": {
"paypal": {
"agreementConfirmation": "AGREE_AND_PAY",
"displayShippingAddress": true,
"overrideShippingAddress": false
},
"returnUrl": "https://<return_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"session": {
"id": "SESSION0002567768179L82204264I7"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<post_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"billingAgreement": {
"description": "Test Billing Agreement",
"name": "Test Name",
"cardinality": "MULTIPLE"
}
}
},
"type": "PAYPAL"
},
"token": "975890899756"
}
{
"browserPayment": {
"redirectUrl": "https://<redirect_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"merchant": "<test_merchant_Id>",
"response": {
"gatewayCode": "NO_VERIFICATION_PERFORMED"
},
"result": "SUCCESS",
"session": {
"id": "SESSION0002567768179L82204264I7"
}
}
检索会话详细信息
此令牌（网关生成的或您在 Tokenize Browser Payment 请求中提供的）在付款会话中存储，在 Tokenize Browser Payment 响应中返回。
如果您配置的是网关生成令牌，请使用 session.id 立即提交 Retrieve Session 请求，然后获取 sourceOfFunds.token 字段中返回的值。 如果付款人无法成功设置账单协议，将不会返回令牌。
如果您配置的是商家提供令牌，请转到步骤 3： 检索账单协议详细信息。
以下是一个会话 ID 的 Retrieve Session 请求的示例，该会话 ID 获取自令牌已由网关生成的 Tokenize Browser Payment 响应。
| URL | https://mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/{sessionId} |
| HTTP 方法 | GET |
{
"merchant": "<test_merchant>",
"session": {
"id": "SESSION0002567768179L82204264I7",
"updateStatus": "SUCCESS",
"version": "82cbc9f602"
},
"sourceOfFunds": {
"token": "975890899756"
},
"version": "72"
}
在 PayPal 上自定义您的账单协议
若要进一步自定义 PayPal 的付款人体验，您可以在 PayPal 上设置协议时提供其他参数。
- 协议名称
- 协议描述
- 商家自定义数据： 商家特定协议数据。
- 跳过送货地址： 如果设置为 true，在协议审批期间不会从付款人那里收集送货地址。
- 不可改变送货地址： 如果设置为 true，送货地址将显示，但不可编辑。
- 包含送货地址： 在送货地址与默认地址不同时，您必须允许付款人提供送货地址。
Tokenize Browser Payment 请求和 PayPal 账单协议配置中的送货地址字段已设置，以在账单协议审批期间提供预期的付款人体验。步骤 3： 检索账单协议详细信息
在根据账单协议继续处理付款前，您必须检查包含协议详细信息的令牌是否有效。 这是因为当令牌状态将变为无效时，付款人可能选择取消 PayPal 网站上的账单协议。 使用无效令牌继续处理付款将导致交易失败。
当付款人返回到 browserPayment.returnUrl 指定的页面时，您可以提交 Retrieve Token 请求。 您必须提供令牌 ID 来检索账单协议详细信息。 如果付款人成功签署了账单协议，将返回以下详细信息。 否则，将返回“未找到令牌”错误。
sourceOfFunds.provided.paypal.billingAgreement.cardinalitysourceOfFunds.provided.paypal.billingAgreement.descriptionsourceOfFunds.provided.paypal.billingAgreement.idsourceOfFunds.provided.paypal.billingAgreement.namesourceOfFunds.provided.paypal.payerIdsourceOfFunds.provided.paypal.accountEmailsourceOfFunds.provided.paypal.accountHolder
以下是一个令牌 ID 的 Retrieve Token 请求的示例，该令牌 ID 获取自 Retrieve Session 响应或由您在 Tokenize Browser Payment 请求中提供。
| URL | https://mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/token/{tokenId} |
| HTTP 方法 | GET |
{
"repositoryId": "TEST8108F6CF-6899-42",
"result": "SUCCESS",
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "test@test.com",
"accountHolder": "FirtName LastName",
"billingAgreement": {
"cardinality": "MULTIPLE",
"description": "Test Billing Agreement",
"id": "B-NGxIf31554266975867",
"name": "Test Name"
},
"payerId": "K4ZK9KRAXRVNA"
}
},
"type": "PAYPAL"
},
"status": "VALID",
"token": "975890899756",
"usage": {
"lastUpdated": "2019-04-03T04:49:48.029Z",
"lastUpdatedBy": "<test_merchant>",
"lastUsed": "2019-04-03T04:49:48.029Z"
},
"verificationStrategy": "NONE"
}
步骤 4： 根据账单协议发起付款
当账单协议通过审批生效后，如果您在 Tokenize Browser Payment 请求中设置了 browserPayment.paypal.agreementConfirmation=AGREE_AND_PAY，则必须根据账单协议立即发起付款。
除了标准字段外，请在 Pay 请求中提供以下字段：
sourceOfFunds.type = PAYPALsourceOfFunds.token: 提供在网关上标识账单协议详细信息（从 PayPal 收到的）的令牌 ID。 您可以为一次付款和定期付款使用此令牌 ID。
您可以通过执行 Retrieve Transaction 操作或通过 Merchant Administration 查看 Authorize 或 Pay 交易的账单协议详细信息。
以下是一个 Pay 交易请求示例，其使用标识与 PayPal 之间的账单协议的令牌。
| URL | https://mtf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP 方法 | PUT |
{
"apiOperation": "PAY",
"order": {
"amount": "123.46",
"currency": "USD",
"description": "Quantity description",
"item": [
{
"name": "name",
"quantity": "40",
"sku": "sku",
"unitPrice": "2.8"
}
],
"itemAmount": "112.00",
"tax": [
{
"amount": "0.29",
"rate": "9.77"
}
],
"taxAmount": "11.46"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"email": "test@test.com",
"firstName": "FirstName"
}
},
"sourceOfFunds": {
"token": "975890899756"
}
}