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:
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.v2/checkout/orders is for the payer approval process. If "intent":"authorize"
is specified at creation, then once authorized (which is a 2nd API call after payer approval) there will be an Authorization object returned for later use (up to 29 days). No money is moved until there is a capture. -- [If you don't want a later-use Authorization object (most integrations do not need one), specify intent:capture at creation instead, and after approval do the corresponding orders capture for your 2nd call instead of authorize.]
v2/payments is for managing authorizations as well as completed captures with a later 3rd API call. For example, to capture or void an authorization within 29 days, or to refund a capture within ~180 days.
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', which the standard integration guide has has a backend sample for here (in node.js, but it can of course be implemented in any language/environment). These two routes should return only JSON data when fetched (no HTML or text). The orders authorize 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 front-end approval flow (see above link for a sample, or this demo: https://developer.paypal.com/demo/checkout/#/pattern/server )