- 集成指南
- 支持的功能（付款方式）
- 实施浏览器付款集成
- PayPal 支付
PayPal
PayPal 是一种受 Mastercard Gateway 支持的浏览器付款方式。 此页介绍特定于 PayPal 的集成详细信息，包括如何将您的 PayPal 企业账户设置为通过网关、按照品牌要求接受付款等。建立您先阅读浏览器付款集成指南，再构建 PayPal 集成。
如果您在 API 版本 50 前已完成集成来使用 PayPal，请单击此处。
先决条件
若要通过 Mastercard Gateway 将 PayPal 用作付款方式，您必须有一个针对网关配置的 PayPal 企业账户。 有关详细信息，请参见配置您的 PayPal 企业账户。
若要注册 PayPal 企业账户，请单击此处。
PayPal 结账体验
以下各部分将帮助您选择最适合您的网站的 PayPal 结账体验。
PayPal 允许您的付款人在购物网站上快速安全地结账，并允许他们使用其 PayPal 账户付款，同时还可以根据需要向网站提供送货信息。 使用 PayPal，付款人在网站上开始和结束结账流程。
网关支持两种 PayPal 结账流 — 使用 PayPal 结账和使用 PayPal 付款。
将 SDK 版本升级到 1.3.0 可以为买家提供 Venmo 和 Pay Later 付款选项。 有关 Venmo 和 Pay Later 的更多信息，请参见使用 Venmo 支付和 Pay Later 优惠（美国）。
“使用 PayPal 结账”流允许您通过使用 PayPal 结账将付款人从您的网站重定向到 PayPal。
- 付款人绕过常规结账流，使用 PayPal 账户内存储的信息结账。
- PayPal 向您提供来自付款人账户的姓名、电子邮件地址和送货地址。 此操作帮助更快地完成结账。
- PayPal 在 PayPal 上收集付款人的送货地址，如果需要，付款人可以添加或编辑此地址。
- 验证订单详细信息后，付款人选择继续按钮。
- 付款人被重定向到您的付款页进行确认。
- 如果需要，您可以在接受付款前更改订单（例如，根据 PayPal 返回的地址添加送货和处理费用）。
示例结账流
下方图表介绍付款人使用 PayPal 存储的送货地址的使用 PayPal 结账流。 付款人在商家网站上审查并确认付款。
此结账流如下所示︰
- 付款人浏览您的网站，选择产品，然后点击结账页的使用 PayPal 结账。
- 当付款人点击使用 PayPal 结账按钮时，您对网关执行
Initiate Browser Payment调用，并将付款人重定向到响应中返回的 PayPal URL。 - 网关将付款人重定向到 PayPal。
- 付款人使用 PayPal 登录页登录到其 PayPal 账户。
- 付款人指定送货地址。 付款人可以选择之前存储在 PayPal 中的收货地址，或输入新地址。
- 付款人选择资金来源并点击 PayPal 上的"继续"按钮继续付款。
- 系统通过网关将付款人从 PayPal 重定向回网站。 您使用
Retrieve Transaction操作检索交易详细信息，包括付款人的账户电子邮件和送货地址。 - 您根据此信息向付款人呈现审查页（例如，您可能希望添加送货和处理费用）。 当付款人单击"立即付款"按钮处理付款时，您将
Confirm Browser Payment调用提交到网关。在单击"立即付款"按钮前，付款人可以选择更新送货地址。 - 网关发送包含交易详细信息的响应，指示付款成功或失败，这样您可以向付款人呈现付款状态。
{
"apiOperation":"INITIATE_BROWSER_PAYMENT",
"browserPayment":{
"operation":"AUTHORIZE",
"paypal":{
"paymentConfirmation":"CONFIRM_AT_MERCHANT"
},
"returnUrl":"Https://test.com"
},
"order":{
"amount":"4.20",
"currency":"USD"
},
"sourceOfFunds":{
"type":"PAYPAL"
}
}
使用 PayPal 付款流允许付款人继续通过常规结账流结账，在网站上输入账单和送货信息。 当系统提示付款人选择付款方式时，付款人选择网站结账页上其他付款选项旁边的 PayPal 选项。 与使用 PayPal 结账交易不同，网站将付款人的送货地址发送到 PayPal。 默认情况下，您可以选择不在 PayPal 上显示送货地址和/或禁用网站上的编辑功能。 请参见下方的显示/覆盖送货地址了解有关如何在 PayPal 集成中实现此目的的信息。 使用“立即付款”按钮，付款人可以在被重定向回网站前在 PayPal 上确认付款。 此选择让您可以为付款人提供更快速的结账体验，因为付款人在 PayPal 上完成付款。
示例结账流
下方图表介绍付款人在 PayPal 上审查并确认付款的使用 PayPal 付款流。
此结账流如下所示︰
- 付款人浏览您的网站，选择产品，然后点击结账页的 PayPal。
- 当付款人点击 PayPal 按钮时，您对网关执行
Initiate Browser Payment调用，并将付款人重定向到响应中返回的 PayPal URL。 - 网关将付款人重定向到 PayPal。
- 付款人使用 PayPal 登录页登录到其 PayPal 账户。
- 付款人通过点击 PayPal 上的“立即付款”按钮审查账单详细信息并确认付款。
- 网关发送包含交易详细信息的响应，指示付款成功或失败，这样您可以向付款人呈现付款状态。
{
"apiOperation":"INITIATE_BROWSER_PAYMENT",
"browserPayment":{
"operation":"PAY",
"paypal":{
"paymentConfirmation":"CONFIRM_AT_PROVIDER"
},
"returnUrl":"Https://test.com"
},
"order":{
"amount":"4.20",
"currency":"USD"
},
"sourceOfFunds":{
"type":"PAYPAL"
}
}
不论是使用使用 PayPal 结账还是使用 PayPal 付款结账流，您都可以选择在 PayPal 上显示"立即付款"按钮或"继续"按钮。
使用"立即付款"按钮，付款人可以在被重定向回网站前在 PayPal 上确认付款。 此选择让您可以为付款人提供更快速的结账体验，因为付款人在 PayPal 上完成付款。
使用"继续"按钮，付款人可以在查看所有订单详细信息后被重定向回网站确认付款。 此选项允许您在接受付款前更改订单（如有必要）（例如，根据 PayPal 返回的地址添加送货和处理费用）。 或者，您可以包括其他结账步骤，例如，在确认订单页追加销售。
请参见下方的付款确认了解有关如何在 PayPal 集成中实现此目的的详细信息。
根据结账流（使用 PayPal 结账或使用 PayPal 付款），您可以选择分别在网站或 PayPal 上收集付款人送货地址。 默认情况下，PayPal 在 PayPal 上收集付款人的送货地址，如有必要，付款人可以添加或编辑此地址。 您可以选择不显示送货地址和/或禁止编辑。 请参见下方的显示/覆盖送货地址了解有关如何在 PayPal 集成中实现此目的的信息。
PayPal 集成
PayPal 作为 Hosted Checkout 的结账选项
如果您使用的是 Mastercard Gateway 付款页 (Hosted Checkout)，当 your payment service provider 在您的商家配置文件中配置了 PayPal 收单行链接时，PayPal 将被作为结账选项自动提供给付款人。 有关详细信息，请参阅通过 Hosted Checkout 集成进行浏览器付款。
PayPal 作为付款页的结账选项
如果您已集成到 API 版本 50 或更高版本，您可以在付款页上将 PayPal 添加为结账选项。 您必须从服务器端应用程序提交 Initiate Browser Payment 请求来发起 PayPal 交互。
付款人将被从您的网站重定向到 PayPal 进行登录、完成付款详细信息。 有关详细信息，请参见通过 Direct Payment 使用 PayPal。
通过 Direct Payment 使用 PayPal
Initiate Browser Payment 请求中的以下字段特定于 PayPal 或在 PayPal 集成中有特定用法。 其他详细信息，请参见通过 Direct Payment 集成使用浏览器付款。
sourceOfFunds.type = PAYPALbrowserPayment.operation=AUTHORIZE或PAY
使用 PayPal，资金可以从授权发生时起保留 3 天（遵守期）。 如果在 3 天后您仍希望过账资金，您可以使用 Update Authorization 操作或通过 Merchant Administration 发起。
默认情况下，您的 PayPal 商家账户被配置为只能过账一次。 如果您希望将配置更改为支持多次过账，请联系 PayPal。-
在发起 PayPal 支付时，您必须指定希望付款人在 PayPal 上还是您的网站确认付款。
如果在提供商 (PayPal) 处确认，PayPal 将显示"立即付款"按钮，允许付款人在被重定向到您的网站前在 PayPal 上确认付款。 您必须向 Mastercard Gateway 提交
Retrieve Transaction请求以确定付款是否成功。如果在您的网站上确认，PayPal 将显示"继续"按钮，允许付款人被重定向到您的网站在网站上确认付款。 您必须将
Retrieve Transaction请求发送到网关以检索付款人是否继续付款的相关详细信息。 如果付款人继续在您的网站上付款，您需要发送Confirm Browser Payment调用向 PayPal 确认付款。Confirm Browser Payment响应将包含有关付款是否成功的信息。Confirm Browser Payment API 参考 [REST][NVP]
在两种情况下，如果付款成功，Retrieve Transaction 将返回：
- 付款人 PayPal 账户中的电子邮件地址
- 付款人 PayPal 账户中的开户人姓名
- 与付款人的 PayPal 账户关联的付款人 ID
- 送货地址详细信息
{ "apiOperation":"CONFIRM_BROWSER_PAYMENT", "order":{ "amount":"4.20", "currency":"USD" } } -
您可以使用两个字段管理付款人如何向您提供送货地址：
browserPayment.paypal.displayShippingAddress— 设置为 true（默认）时，送货地址在 PayPal 上显示。browserPayment.paypal.overrideShippingAddress— 设置为 true（默认）时，付款人可以更改 PayPal 上的送货地址。
默认情况下，PayPal 在 PayPal 上从付款人处为您收集送货地址。 如果您选择在您的网站上收集送货地址，且您不希望 PayPal 向付款人显示送货地址，则必须将
browserPayment.paypal.displayShippingAddress设置为 false。 当订单不需要送货地址时（例如，仅购买数字产品）此方法也适用。如果在
Initiate Browser Payment请求中提供地址或如果将browserPayment.paypal.displayShippingAddress设置为 true，将始终在Retrieve Transaction响应中返回送货地址。如果付款人在 PayPal 上更改了送货地址，您应该使用交易响应中返回的送货地址。 请注意，PayPal 会验证美国送货地址的城市、州、邮政编码组合。 -
您可以在
Initiate Browser Payment请求中指定单项商品详细信息，以在付款人确认付款前向付款人提供所有订单详细信息。 消费者调查显示，当买家在 PayPal 结账期间看到订单的单个商品及其他详细信息时，完成购买的概率更大。 因此，建议您在发起 PayPal 结账时提供订单信息，以鼓励付款人继续付款而不是放弃。如果指定了商品名称或单价，则视为提供了单项商品。 有关单项商品详细信息的更多信息，请参见单项商品数据。
如何解释交易结果
下表显示了在发起浏览器付款后您可能遇到的可能出现的情景的交易响应代码。
Initiate Browser Payment 响应 |
具体含义... |
|---|---|
response.gatewayCode=SUBMITTEDresult=SUCCESS |
使用响应中提供的 URL 重定向付款人。 |
response.gatewayCode=SUBMITTEDresult=FAILURE or PENDING or UNKNOWN |
提交另一个 INITIATE_BROWSER_PAYMENT 请求。 |
Retrieve Transaction/Retrieve Order 响应 |
具体含义... |
response.gatewayCode=APPROVEDresult=SUCCESS |
付款成功。 |
response.gatewayCode=PENDINGresult=PENDING |
付款在 PayPal 系统中等待审查。 请参见待处理付款。 |
response.gatewayCode=CANCELLEDresult=FAILURE |
付款人已取消此付款的交互。 为付款人提供尝试其他付款方式的选项。 |
response.gatewayCode=DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTEDresult=FAILURE |
付款被 PayPal 拒绝。 |
response.gatewayCode=ACQUIRER_SYSTEM_ERRORresult=FAILURE |
收单行无法处理交易。 您可能需要询问收单行付款失败的原因，也可以重试 RETRIEVE_TRANSACTION。 或者，您可以为付款人提供尝试其他付款方式的选项。 |
response.gatewayCode=SYSTEM_ERRORresult=FAILURE |
网关无法处理交易。 |
response.gatewayCode=TIMED_OUTresult=FAILURE |
付款人与 PayPal 系统之间的交互未成功完成，例如，网关未在 24 小时内收到来自商家的付款人浏览器的重定向，或网关无法检索到付款人与 PayPal 系统之间的交互详细信息，因此付款未完成。 |
response.gatewayCode=UNKNOWNresult=UNKNOWN |
网关无法查找付款成功或其他结果的信息。 |
授权更新
您可以使用 Update Authorization 操作或通过 Merchant Administration 为有效的 PayPal 授权交易更新授权遵守期和/或增加授权金额。 为此，您必须让 your payment service provider 在您的商家配置文件中启用“更新授权”权限。 有关详细信息，请参见 Update Authorization。
建议您在最初的 3 天（遵守期）后更新授权以确保资金仍然可用。 重新授权的付款有另外 3 天的遵守期。 在 29 天的有效期内，3 天遵守期最多可以更新一次。
您可以更新授权一次，最多更新为初始授权金额的 115% 或 75 美元。
过账、退款和取消
对于 PayPal 付款，您可以使用 Capture 操作或通过 Merchant Administration 过账初始授权金额的部分或全部授权金额。
您可以部分或全部退还通过 PayPal 处理的 Pay 和 Capture 交易的付款。 您可以使用 Refund 操作或使用 Merchant Administration 提交 Refund 请求。
如果过账尝试失败，您可以取消任何已授权交易，也可以退还 Pay 交易的款项来撤消付款。 您可以使用 API 操作、Void 和 Refund 或通过 Merchant Administration 提交 Void 或 Refund 请求。
待处理付款
网关可能在交易响应中返回 PENDING 状态。 例如，如果交易当前在 PayPal 进行风险评估。 如果状态为待处理，并且您已配置了自己的欺诈管理筛选器，则您应该登录到您的 PayPal 企业账户并审查付款。 当 PayPal 更新待处理交易的状态时，PayPal 将通知网关。
账单协议和定期付款
使用“使用 PayPal 结账”或“使用 PayPal 付款”，您可以为付款人设置账单协议，这允许您根据此账单协议发起参考交易（订阅/重复或按需付款），而无需付款人额外同意。 有关更多信息，请参见账单协议和定期付款。
配置 PayPal 集成
要通过 PayPal 处理交易，您必须授予网关代表您向 PayPal 提交交易请求的权限。 要授予第三方权限，您必须登录 Merchant Administration 门户。 在 PayPal 配置页面上，您可以看到 your payment service provider 已经为您配置的 PayPal 商家收单行链接。 如果您未授予第三方收单行链接权限，账户 ID 字段将保留为空。 因此，您必须向网关授予权限，让网关能够代表您发起 API 调用。
要使用新的电子邮件账户为 PayPal API 授予第三方权限：
- 要为特定收单行链接授予第三方权限，请选择启用。
- 在 PayPal 页面上输入所需的详细信息，然后选择下一步。
- 输入所需的详细信息，然后选中用户协议、隐私声明复选框。
- 选择同意并创建账户。
- 输入业务相关信息，然后单击下一步。
- 输入用户相关信息，然后单击提交。
注册确认页面将显示如何激活您的 PayPal 账户的说明。
- 根据发送到您在注册时输入的电子邮件地址的说明激活您的 PayPal 账户。
- 按照屏幕上的说明返回到 Merchant Administration 页面。
已为特定 PayPal 收单行链接授予所需的第三方权限。 状态已启用并显示 PayPal 账户 ID。
- 要撤消第三方权限，选择禁用，要更新信息，选择更新。
如果由于出现问题导致第三方权限失败，将显示错误消息。
要使用已注册的电子邮件账户为 PayPal API 授予第三方权限：
- 要为特定收单行链接授予第三方权限，请选择启用。
- 在 PayPal 页面上输入所需的详细信息，然后选择下一步。
- 输入您的凭据，然后选择登录。
您已成功注册并集成 PayPal。
- 按照屏幕上的说明返回到 Merchant Administration 页面。
已为特定 PayPal 收单行链接授予所需的第三方权限。 状态已启用并显示 PayPal 账户 ID。
- 要撤消第三方权限，选择禁用，要更新信息，选择更新。
如果由于出现问题导致第三方权限失败，将显示错误消息。
增强卖家保护
在执行 Tokenize Browser Payment 来允许 PayPal 在处理交易前对交易执行风险评估后，您可以在 Initiate Browser Payment 和后来的 Pay 或 Authorize 请求中提交其他付款人数据。
以下字段中的数据由 PayPal 用来执行交易前风险管理评估：
device.fingerprint: 可以使用 PayPal FraudNet Javascript 库生成的设备的唯一标识符。 这样，PayPal 可以对交易执行风险评估。risk.custom: 您可以在此字段中提供有关付款的其他数据。 您必须就希望提供的值与 PayPal 达成协议。 例如，risk.custom.headOfficeLocation=London UK。sourceOfFunds.token: 在网关上标识账单协议详细信息（从 PayPal 收到的）的令牌 ID。 您可以为一次付款和定期付款使用此令牌 ID。 有关更多信息，请参见账单协议和定期付款。对于直接付款，sourceOfFunds是 PayPal。
超额退款
超额退款必须在 PayPal 网站上启用。 您可以通过 Capture 请求或 Merchant Administration 过账超出的授权金额。
允许的超额过账金额最多为初始授权交易的 115%。 您可以退还通过 PayPal 处理的 Pay 和 Capture 交易的超额付款。
您可以通过 Refund 操作或 Merchant Administration 提交 Refund 请求。
对于超额退款，请包括超出初始交易金额的金额。 要退还超出的过账金额，请确保您在 PayPal 商家配置文件中启用了超额退款。
如果您的 PayPal 配置文件启用了超额退款，请确保为此配置您的 Mastercard Gateway 商家配置文件。
测试您的集成
Mastercard Gateway 提供 PayPal 模拟器，允许您测试您的集成能否通过网关使用 PayPal 功能。