Paypal：Orders API 与 Payments API，并找到更好的文档

Posted 2023-02-22

【中文标题】Paypal：Orders API 与 Payments API，并找到更好的文档

【英文标题】：Paypal: Orders API vs Payments API, and finding better documentation

【发布时间】：2021-08-01 05:07:10

【问题描述】：

我完全迷失在 PayPal 的 API 文档中。我一直在使用订单 API 和 PayPal Checkout SDK 尝试为项目设置付款。在尝试破译 Orders v2 API 参考时，为了使用对先前授权的订单总数进行多次捕获，我发现了一堆似乎更有用的文档来讨论 Payments API。我无法理解两者之间的区别是什么，或者我应该使用哪个或用于什么。

Orders API Reference 表示如下：

订单代表两方或多方之间的付款。使用 Orders API 创建、更新、检索、授权和捕获订单。

虽然Payments API Reference 这么说：

调用Payments API授权支付，获取授权 付款，退还已捕获的付款，并显示 支付信息。将 Payments API 与 订单 API。有关详细信息，请参阅 PayPal 结帐概述。

他们都在描述做几乎完全相同的事情，并且 Payments API 表示它应该与 Orders API 结合使用，而实际上并未就如何一起使用它们提供任何指导。给出的“结帐概述”链接指向带有 Orders API 的智能按钮指南，实际上并未提及 Payments API。

所以我的主要问题如下：

这两个 API 有什么区别？ 我需要使用哪个 API 来支持多个捕获？似乎 Payments 是唯一支持多次捕获的，但我已经有基础设施，仅使用 Orders API 创建intent=AUTHORIZE 交易，将order_id 发送到客户端，以便可以弹出 PayPal 和order 授权，以及一个 webhook 来接收该授权的通知。我现在可以使用 Payments API 来获取信息吗？我什至需要吗？我在订单文档中找不到与多次捕获相关的任何内容。 是否有任何其他好的文献描述了 Checkout SDK 和 Orders/Payments API 的所有移动部分如何为较小规模的项目组合在一起？ PayPal 自己的指南随处可见，几乎没有描述不同部分如何交互或何时需要一个 API 与另一个 API。

【问题讨论】：

paypal 文档被认为是最糟糕的文档之一

据我所知，随着时间的推移，情况似乎变得更糟了。很久以前的 IPN 文档似乎相对干净（授予其更简单的系统），甚至 v1 文档对其大部分部分都有一些很好的书面解释

【参考方案1】：

v2/orders 用于付款人审批流程。使用"intent":"authorize"，成功的订单将产生一个授权对象供以后使用。

v2/payments 用于管理授权和完成的捕获。例如，获取授权或作废授权，或退还获取的款项。

---

您提到了 webhook，这可能使事情变得过于复杂。最好的集成是在您的服务器上简单地创建两条路由，一条用于“创建订单”，一条用于“授权订单”，documented here。这些路由应该只返回 JSON 数据（没有 html 或文本）。后者应该（成功时）在返回之前将付款详细信息存储在您的数据库中（特别是purchase_units[0].payments.authorizations[0].id）

将这两条路线与以下批准流程配对：https://developer.paypal.com/demo/checkout/#/pattern/server

【讨论】：

我的服务器上应该有一个“授权订单”路由是什么意思？用户不是在 PayPal 弹出窗口中完成授权吗？另外，如果我不使用 webhook，如何安全地处理授权？如果我依靠onapprove 回调进行支付处理，用户就不能搞砸吗？

否，用户批准订单。 Orders v2 流程的最后一步是使用相应的 API 调用进行授权（对于意图：授权）或捕获（对于意图：捕获）。这会产生付款对象。

批准发生在客户端，它需要告诉您的服务器这已经发生，以便它可以继续授权。这正是onApprove 回调的用途，没有这个就无法进行。

理论上，注册CHECKOUT.ORDER.APPROVED webhook 并在异步接收此 webhook 时进行授权在技术上是可行的。但是，您将无法立即通知用户生成的支付授权成功（或失败并要求他们重试）。因此onApprove 函数是唯一正确的方法，并且为此目的而存在。

哦，我必须做授权。这是导致我困惑的关键缺失细节。我的印象是用户授权了我创建的订单，然后我根据该授权进行了捕获。