Launch v2 PayPal Checkout APIs

We are pleased to announce the general availability of the next generation APIs (v2/checkout/orders) and Payments (v2/payments). These are the foundation for enabling PayPal Checkout using Smart Payment Buttons and underpin an innovative new payment experience we are rolling out worldwide in the coming months.

This release does not impact the PayPal merchants, developers and partners currently integrated with PayPal Checkout. We will, of course, continue to support all current integrations and make priority bug fixes but the current REST API v1/payments will henceforth be marked as deprecated and new integrations are discouraged.

Why v2?

The new v2 APIs do the heavy lifting for merchants and developers. They deliver a comprehensive and holistic solution that benefits all users. They include a cohesive and consistent set of API endpoints encompassing PayPal’s current and future payment processing capabilities to serve all merchants the world over.

Improvements include:

• API interfaces reimagined to closely match a merchant/partner’s world view viz. Order, Authorization, Capture and Refunds.
• Minimal number of required fields. Start small with just 5 lines of JSON to Create an Order and customize with other optional fields as the use case demands.

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "CAPTURE",
  "purchase_units": [{
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }]
}'

• Capturing an Order is equally simple as below once the payer has approved the Order within the PayPal Checkout flow:

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/order_id/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"
-d '{}'

• Streamlined API interface that removed redundancies and obscure fields. As an example, in our current REST interfaces merchant would have to call either of the below end points to refund depending on if they did a “SALE” or an “AUTH CAPTURE” transaction

POST v1/payments/payment/sale/{sale_id}/refund
POST v1/payments/payment/capture/{capture_id}/refund
With this launch we would have a single end point to refund
POST v2/payments/captures/{capture_id}/refund

• Clear error messaging and the addition of new granular messaging with actionable details.

Note that although the actual API interfaces have evolved, our core payments processing platform remains unchanged, ensuring similar performance, stability and availability.

We are releasing the v2 APIs in a fully tested and validated state. We have piloted the APIs with merchants and partners in limited release for nearly 12 months prior to public availability. They have also been available internally and stress-tested by our worldwide sales engineers and professional services team since early 2018.

Hundreds of PayPal team members and stakeholders around the world have collaborated on and contributed to our v2 APIs. More than once over the course of the development journey, we came close to launching the APIs but realized we hadn’t solved the merchant and developer problems we’d set out to fix. Rather than releasing a sub-standard experience, we re-focused and did better, holding off until we had it right.

Ready to switch?

If you are signing up now or are about to start to integrate, we encourage you to start with the new v2 APIs. Please view the PayPal Checkout Integration Guide to get started. New enhancements and improvements will only be launched on these.

If you already have PayPal Checkout integrated, we have explained the steps you need to follow to successfully switch to the new v2 APIs. See Upgrade PayPal Checkout integration.

Down memory lane…

PayPal was an early pioneer in opening up its platform, enabling thousands of small merchants to integrate the PayPal button on their website with just a few clicks. As our business grew, bigger merchants signed up to offer PayPal, and with that followed the need to simplify back office processing (e.g. refunds). To support that user need, we launched our first ever SOAP API in 2004. In 2013, as the industry and API paradigms evolved, we launched our flagship v1/payments REST API.

As PayPal’s Checkout APIs grew organically over the past decade, so too did the complexity around what we offered, and how we were asking merchants to integrate. For example, with case-specific APIs (e.g. Sale, Authorize & Capture, Multiple Authorizations & Multiple Capture, Credit Card Processing), which made merchant integrations time consuming and re-integrations expensive as business and corresponding needs evolved.

Today, we want our merchants to integrate with an API once, and easily upgrade to get access to all the capabilities that PayPal has to offer.

Focus on documentation

We have taken great care to ensure that the resource names, end points and fields are intuitive. We know too that equally good documentation is key to a successful integration and a positive merchant/developer experience.

We have restructured our integration guides, to enable our developer community to get started with a basic integration as quickly as possible, with options to customize and solve for complex use cases when the need arises.

Let us know what you think

Here at PayPal we are passionate and committed to your success. We encourage you to try our new APIs and share your feedback so we can further streamline and continue to improve your integration experience.