- 集成指南
- 支持的功能（付款方式）
- 实施浏览器付款集成
- PayPal NVP 支付
PayPal NVP
PayPal 是一种受 Mastercard Gateway 支持的浏览器付款方式。 此页介绍特定于 PayPal NVP API 的集成详细信息，包括如何将您的 PayPal 企业账户设置为通过网关、按照品牌要求接受付款等。建立您先阅读浏览器付款集成指南，再构建 PayPal 集成。
先决条件
若要通过网关将 PayPal 用作付款方式，您必须有一个针对网关配置的 PayPal 企业账户。 有关详细信息，请参见配置您的 PayPal 企业账户。
若要注册 PayPal 企业账户，请单击此处。
PayPal 集成
如果您已有 Hosted Checkout 集成，your payment service provider 成功配置 PayPal 收单行链接后，PayPal 即会自动可用。
有关详细信息，请参阅通过 Hosted Checkout 集成进行浏览器付款。
如果您希望在自己的结账页提供 PayPal 付款方式，请选择 Direct Payment 集成。
PayPal 结账体验
您可以选择最适合您的购物网站的结账流。
PayPal 允许您的付款人在购物网站上快速安全地结账，并允许他们使用其 PayPal 账户付款，同时还可以根据需要向购物网站提供送货信息。 使用 PayPal，付款人在购物网站上开始和结束结账流程。 付款人只需登录他们的 PayPal 账户并确认他们的送货地址和付款方式。 购物网站随后可以检索送货信息。
网关支持两种 PayPal 结账流 — Shortcut 和 Mark。
Shortcut 流允许您使用“使用购物网站上的 PayPal 按钮结账’的卡审查页将付款人从您的购物网站重定向到 PayPal 网站。 付款人绕过常规结账流，使用 PayPal 账户内存储的信息结账。 PayPal 向购物网站提供付款人账户的姓名、电子邮件地址和送货地址，让付款人无需在购物网站输入信息，从而实现更快速的结账。
Mark 流允许付款人继续通过常规结账流结账，在购物网站上输入账单和送货信息。 当系统提示付款人选择付款方式时，付款人选择购物网站结账页上其他付款选项旁边的 PayPal 选项。 与 Shortcut 交易不同，购物网站将付款人的送货地址发送到 PayPal。
通过 Shortcut 和 Mark 结账流，您可以选择在 PayPal 网站上显示"立即付款"按钮或"继续"按钮。
"立即付款"按钮可让付款人在重定向回您的购物网站之前在 PayPal 网站上确认付款。 此选择允许您为付款人提供更快速的结账体验，因为付款人在 PayPal 网站完成付款。
"继续"按钮允许付款人在查看所有订单详细信息后被重定向回购物网站确认付款。 此选项允许您在接受付款前更改订单（如有必要）（例如，根据 PayPal 返回的地址添加送货和处理费用）。 或者，您可以包括其他结账步骤，例如，在确认订单页追加销售。
请参见下方的付款确认了解有关如何在 PayPal 集成中实现此目的的详细信息。
根据结账流（Mark 或 Shortcut），您可以选择分别在购物网站或 PayPal 网站上收集付款人送货地址。 默认情况下，PayPal 会在 PayPal 网站上向付款人收集送货地址，付款人可以根据需要添加或编辑此地址。 您可以选择不显示送货地址和/或禁止编辑。 请参见下方的显示/覆盖送货地址了解有关如何在 PayPal 集成中实现此目的的信息。
下方示例描述了 Shortcut 流，在此流中，付款人使用 PayPal 存储的送货地址。 付款人在商家购物网站上审查并确认付款。
此结账流如下所示︰
- 付款人浏览您的购物网站，选择产品，然后点击结账页的使用 PayPal 结账。
- 当付款人单击使用 PayPal 结账按钮时，您将对网关执行
Initiate Browser Payment调用，将付款人重定向到响应中返回的 URL。 - 网关将付款人重定向到 PayPal 网站。
- 付款人使用 PayPal 登录页登录到其 PayPal 账户。
- 付款人指定送货地址。 付款人可以选择之前存储在 PayPal 中的收货地址，或输入新地址。
- 付款人选择资金来源，并通过单击 PayPal 网站上的"继续"按钮继续付款。
- 系统通过网关将付款人从 PayPal 重定向回购物网站。 您使用
Retrieve Transaction操作检索交易详细信息，包括付款人的账户电子邮件和送货地址。 - 您根据此信息向付款人呈现审查页（例如，您可能希望添加送货和处理费用）。 当付款人单击"立即付款"按钮处理付款时，您对网关执行
Confirm Browser Payment调用。 - 网关发送包含交易详细信息的响应，指示付款成功或失败，这样您可以向付款人呈现付款状态。
Initiate Browser Payment API 参考 [REST][NVP]
Direct Payment 集成
Direct Payment 集成允许您在自己的结账页面提供 PayPal 付款方式。
Initiate Browser Payment 请求中的以下字段特定于 PayPal 或在 PayPal 集成中有特定用法。 其他详细信息，请参阅通过 Direct Payment 集成进行浏览器付款。
sourceOfFunds.type = PAYPAL-
使用 PayPal，授权将在授权发生后 3 天内过期。 如果在授权过期后您仍然希望过账资金，可以使用 Update Authorization 操作。
默认情况下，您的 PayPal 商家账户被配置为只能过账一次。 如果您希望将配置更改为支持多次过账，请联系 PayPal。 -
当发起 PayPal 付款时，您必须指定是否希望付款人在 PayPal 网站或您的购物网站上确认付款。
如果在提供商 (PayPal) 处确认，PayPal 网站将显示"立即付款"按钮，允许付款人在被重定向到您的购物网站前在 PayPal 网站上确认付款。 您必须发送
Retrieve Transaction请求到网关来确定付款是否成功。如果在您的购物网站上确认，PayPal 网站显示"继续"按钮，允许付款人被重定向到您的购物网站在网站上确认付款。 您必须将
Retrieve Transaction请求发送到网关以检索付款人是否继续付款的相关详细信息。 如果付款人继续在您的购物网站上付款，您需要发送Confirm Browser Payment调用向 PayPal 确认付款。Confirm Browser Payment响应将包含有关付款是否成功的信息。Confirm Browser Payment API 参考 [REST][NVP]
在两种情况下，如果付款成功，Retrieve Transaction 将返回：
- 付款人 PayPal 账户中的电子邮件地址
- 付款人 PayPal 账户中的开户人姓名
- 送货地址详细信息
-
您可以使用两个字段管理付款人如何向您提供送货地址：
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响应中返回送货地址。请参见下表了解您的集成适用的各种方案。 您可以为每次付款选择不同方案。
Initiate Browser Payment PayPal 网站 显示送货地址 覆盖送货地址 是否需要送货地址？ 是否提供送货地址？ 送货地址是否有效？ 是否向付款人显示送货地址？ 显示的送货地址的来源 付款人能否更改送货地址？ true（默认） true（默认） 可选 否 NA 是 PayPal 收集送货地址。 是 true（默认） true（默认） 可选 是 是 是 PayPal 会在 PayPal 网站上显示您在请求中提供的送货地址。 是 true（默认） true（默认） 可选 是 否 是 PayPal 忽略您在请求中提供的送货地址，而在 PayPal 网站收集送货地址。 是 true（默认） false 必需 是 是 是 PayPal 会在 PayPal 网站上显示您在请求中提供的送货地址。 否 true（默认） false 必需 是 否 否 PayPal 拒绝请求。 不适用 false 不适用 不适用 是 是 否 PayPal 忽略您在请求中提供的送货地址。 否 false 不适用 不适用 不适用 不适用 否 PayPal 没有要显示的送货地址。 不适用 对于所有方案，如果付款人在 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 系统中等待审查。 当 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 |
网关无法查找付款成功或其他结果的信息。 |
待处理付款
在某些情况下，网关可能会在交易响应中返回 PENDING 状态。 例如，如果交易当前在 PayPal 进行风险评估。 如果状态为待处理，并且您已配置了自己的欺诈管理筛选器，则您应该登录到您的 PayPal 企业账户并审查付款。
当 PayPal 更新待处理交易的状态时，PayPal 将通知网关。 您可以使用 Retrieve Transaction 操作检索更新后交易的结果。
网关将 PENDING 交易视为成功，直到收到有关交易成功与否的通知。 订单总额（授权/过账/退款总额）根据待处理交易更新。 如果交易被拒绝，更新将被撤消。
退还 PayPal 付款
您可以部分、全额或超额退还通过 PayPal 处理的付款；但是，请注意，退款金额仅应用于您希望对其执行退款的特定 Capture 交易，而不是授权总额。 例如，如果授权 100 USD 后执行两次部分过账，30 USD (Capture 1) 和 70 USD (Capture 2)，那么此订单的任何退款金额，不论是部分、全额还是超额，将分别应用于 Capture 1 或 Capture 2，而不是订单总额 100 USD。 换言之，50 USD 退款对于 Capture 1 和 Capture 2 分别被视为超额退款和部分退款。
- API 和退款金额（包括已尝试退款）超出过账金额的金额不能超过允许的最大超出额度。
- PayPal，如果 PayPal 收单行拒绝请求。
购物网站的品牌要求
此部分帮助您配置结账页面以符合 PayPal 的品牌要求。
当您将 PayPal 作为付款方式向付款人提供时，务必确保付款人的结账体验达到或超过 PayPal 规定的最佳结账实施标准。
若要为付款人提供更加无缝的体验，网关建议您自定义您的 PayPal 付款页。 为此：
- 登录您的 PayPal 账户（位于 https://www.paypal.com）。
- 确定您是否在使用 PayPal Merchant Manager。 为此，请查看浏览器地址栏中的 URL。 如果 URL 以 https://paypalmanager.paypal.com/ 开头，说明您使用的是 PayPal Merchant Manager。
- 如果您使用 PayPal Merchant Manager：
- 单击配置文件。
- 在托管付款设置下，单击自定义页面样式。
- 如果您未使用 PayPal Merchant Manager：
- 在配置文件下，单击我的销售工具。
- 在在线销售下，单击自定义付款页右边的更新链接。
- 如果您使用 PayPal Merchant Manager：
有关如何在结账页面显示用户界面元素的指南，请参阅 PayPal 网站上的快速结账用户界面标准指南 。
配置 PayPal 企业账户
此部分介绍如何配置您的 PayPal 企业账户来使用网关集成。
若要通过 PayPal 处理交易，您必须向网关授予网关必须代表您发起特定 API 调用的权限。
为此：
- 登录到您的 PayPal 企业账户（位于 https://www.paypal.com）。
- 确定您是否在使用 PayPal Merchant Manager。 为此，请查看浏览器地址栏中的 URL。 如果 URL 以 https://paypalmanager.paypal.com/ 开头，说明您使用的是 PayPal Merchant Manager。
- 如果您使用 PayPal Merchant Manager：
- 单击配置文件。
- 在账户信息下，单击请求 API 凭据。
- 单击设置 PayPal API 凭据和权限。
- 如果您未使用 PayPal Merchant Manager：
- 在配置文件下，单击我的销售工具。
- 在在线销售下，单击 API 访问右边的更新链接。
- 在选项 1 框中，会有一个链接，显示授予 API 权限或添加或编辑 API 权限。
- 如果链接显示授予 API 权限，单击此链接。
- 如果链接显示添加或编辑 API 权限，单击它，然后单击添加新的第三方。
- 在第三方权限用户名框内，输入 Mastercard 提供的 API 用户名，然后单击查找。 API 用户名将在 Mastercard 发送的商家设置电子邮件中提供。
- 在可用权限部分，单击以下复选框：
- 使用 Express Checkout 处理付款。
- 针对特定交易发放退款。
- 授权后过账您的 PayPal 交易。
- 单击添加。
您需要向 your payment service provider 提供您的 PayPal 企业账户的电子邮件地址。
使用这些详细信息，your payment service provider 将完成配置。 当针对 PayPal 网关的集成完成后，您便可以使用 PAYPAL 作为付款类型来发起浏览器付款。 根据您的集成，您可能必须提供一些特定于 PayPal 的字段，以下部分列出了这些字段。
测试您的集成
网关提供 PayPal 模拟器，允许您测试您的集成能否通过网关使用 PayPal 功能。