Paypal: Orders API vs Payments API, and finding better documentation

Question

I am completely lost among PayPal's API documentation. I have been working with the orders API and the PayPal Checkout SDK trying to set up payments for a project. In trying to decipher the Orders v2 API reference, for the use of making multiple captures towards a previously authorized total for an order, I found a bunch of what seemed to be more useful documentation discussing the Payments API instead. I'm having trouble understanding what the difference between the two are or which I should be using or for what.

The Orders API Reference says the following:

An order represents a payment between two or more parties. Use the Orders API to create, update, retrieve, authorize, and capture orders.

While the Payments API Reference says this:

Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview.

They are both describing doing almost the exact same things and the Payments API says it should be used in conjunction with the Orders API without actually providing any guidance for how they should be used together. The "Checkout Overview" link given goes to the guide for Smart Buttons with the Orders API and doesn't actually ever mention the Payments API.

So my main questions are as follows:

• What is the difference between the two APIs?
• Which API do I need to use to support multiple captures? It seems like Payments is the only one which supports multiple captures but I already have infrastructure in place using only the Orders API to create an intent=AUTHORIZE transaction, have the order_id sent to the client so that PayPal can be popped up and the order authorized, and a webhook to receive the notification for that authorization. Can I now use the Payments API just to capture from that? Do I even need to? I can't find anything related to multiple captures in the Orders documentation.
• Is there any other good literature describing how all of the moving parts of the Checkout SDK and the Orders/Payments API fit together for a smaller scale project? PayPal's own guides are all over the place and do very little to describe how the different parts interact or when you need one API vs the other.

Answer 1

v2/orders is for the payer approval process. With "intent":"authorize", a successful order will result in an Authorization object for later use.

v2/payments is for managing authorizations as well as completed captures. For example, to capture or void an authorization, or to refund a capture.

---

You mentioned webhooks, which is probably overcomplicating things. The best integration is to simply make two routes on your server, one for 'Create an Order' and one for 'Authorize an Order', documented here. These routes should return only JSON data (no HTML or text). The latter one should (on success) store the payment details in your database before it does the return (particularly purchase_units[0].payments.authorizations[0].id)

Pair those two routes with the following approval flow: https://developer.paypal.com/demo/checkout/#/pattern/server