Category Archives: Announcements

API Style Guide and Patterns: The Evolutionary Journey Continues


APIs as Products

Around four years ago, we began the journey at PayPal to transform all of PayPal’s core capabilities into a platform of discoverable, well-encapsulated, reusable API-driven products. We have used a customer-oriented approach to go from a very monolithic and siloed architecture to a much more loosely coupled set of over 150 services with well designed, modern APIs. We framed this transformational exercise as an organizational change initiative, with the goal of bringing a fundamental shift in how we design and build APIs. We made it a priority to identify and serve all key “customer” constituencies – developers who design and build APIs, developers who create innovative applications using these APIs, as well as the executives who support these efforts. This mindset influenced the strategy, the processes and the tools that we put together, our communication with the stakeholders, and the definition and measurement of success. An unflinching focus on developer experience and satisfaction has been key to our success, and it continues to shape how we manage this transformational program today.

While every company has its own unique culture and challenges, many of the very valuable and insightful lessons that we have learned, and the approaches that we have utilized, are applicable to other companies that are trying to chart the same course.


At the beginning of our API journey at PayPal, we started off thinking about what common ideas would guide us towards our goal of nicely encapsulated services that exposed well-designed, reusable APIs. These became our core principles and directed much of our subsequent standards evolution, as well as the criteria for measuring API quality.

  • Loose Coupling

Services and consumers must be loosely coupled from each other.

  • Encapsulation

A domain service can access data and functionality it does not own through other service contracts only.

  • Stability

Service contracts must be long-lived with a predictable lifecycle.

  • Reusable

Services must be developed to be reusable across multiple contexts and by multiple consumers.

  • Contract-Based

Functionality and data must only be exposed through standardized service contracts.

  • Consistency

Services must follow a common set of rules, interaction styles, vocabulary and shared types.

  • Ease-of-Use

Services must be easy to use and composable by consumers.

  • Externalizable

Services must be designed so that the functionality these provide is easily externalizable.

API Schema

We decided on REST/JSON as the primary interface standard. Next, we wanted all service developers to use a consistent schema format to document their APIs so that we could leverage seamless discovery, machine interpretation, and common tooling and infrastructure. When we started, we adopted Google Discovery Document (GDD) as the schema format for API specifications. There was not much of community support and adoption for this standard, and we ended up developing significant amount of tooling and support for GDD.

However, in late 2015, as the industry started to throw its weight behind Open API Specification (known then as Swagger), PayPal joined the movement and became one of the founding members of the Open API Initiative, an open-source project under the Linux Foundation. This year we began migrating our API schemas to OpenAPI, and are seeing early dividends in terms of reduced infrastructure investment, better stability and happier developers.

API Style Guide

We have developed a comprehensive API style guide to help ensure consistency across the product teams that contribute to the design and development of PayPal’s REST APIs. The style guide includes aspects such as:

  • URI structure
  • header usage
  • status codes
  • resource naming
  • query parameters
  • schema and types
  • request and response representations
  • error handling
  • versioning
  • deprecation
  • security
  • hypermedia
  • API design patterns and use-cases

An initial version of this style guide was open sourced in April 2015. The API style guide and the design patterns therein have evolved a lot since. Today, we announce the general availability of the latest API style guide.

Download the API Style Guide from PayPal’s public GitHub.

We hope this style guide will help you scale your API journey faster.

Nikhil Kolekar

Author: Nikhil Kolekar

About the author: Nikhil Kolekar is a founding member of PayPal’s API Platform team and is passionate about the disruptive innovation that digital transformation initiatives are bringing to the contemporary world. He and his team are working hard to make seamless inter-networked commerce a reality.

New REST API Feature: Setting a Receiver for Payments


Until recently, if you have been using the PayPal REST APIs to process payments, you will have seen that the money transacted is always paid to the app owner, known as the payee or receiver. The ability to change the receiver of funds in a transaction by setting a different payee has been a highly requested feature by our developer community.

With that said, we’re happy to share that you can now set the payment receiver when making direct payments in the REST APIs. When setting your payment transaction details, before starting the payment, simply add a payee object and include the email address of the account that should receive the payment. A sample payment JSON object that includes a payee email may look something like this:

            'email': ''
        'description':'My amazing product'

You can see the full payee object definition in our API documentation.

Currently this functionality is available globally, where PayPal is available, for standard PayPal and credit card payments through the REST APIs only, but we’re working hard to get it enabled for all feature endpoints. Please note that direct credit card payments and their related features are restricted in some countries.

Happy coding!

Integrate our new JavaScript SDK for Payments


PayPal’s Braintree is a core building block for accepting payments on the web, enabling merchants to accept PayPal, credit cards, 3D Secure, Apple Pay, Android Pay, and more.

This year, we introduced a new version of our Braintree JavaScript SDK (Software Development Kit). With numerous improvements such as a smaller file size, greater flexibility, and input formatting, this modernized JS SDK is ready for the web of today and tomorrow.

We’re pleased to announce General Availability of v3 of the Braintree JS SDK, ready for you to integrate and use right away. This SDK is a great way to accept PayPal on your website, and we recommend that you use it for new PayPal integrations.

Braintree offers additional features above what you’ll find in PayPal alone, including support for additional payment methods. Also, you’ll have a simple path toward accepting new payment methods in the future.

This new SDK is now open source on GitHub. Want to change or improve something? We welcome pull requests.

Ready to get started? Visit our Braintree JS documentation, and let us know what you think!

Braintree Product Team

Adaptive Payments is Moving to Limited Release – What you Need to Know


On October 6th we will begin the process of moving the Adaptive Payments product into a limited release mode. Limited release means a few things for Adaptive Payments in this case:

  • Adaptive Payments will be restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.
  • The Adaptive Payments documentation will only be accessible from a single new location, the documentation directory.
  • All references to Adaptive Payments as a solution within the documentation will be removed / replaced with the best current solutions.

Adaptive Payments will continue to be a fully supported offering, so integrations will continue to function without interruption. Our end goal with this project is to migrate all existing users of Adaptive Payments on to the modern products that will be the core of our future development APIs, namely Braintree and the PayPal REST APIs.

Why we’re moving to a limited release

This is the first step in a far reaching effort to continue to provide modern offerings, and the best solutions, for developers. To continue this, we are centralizing our efforts behind the development and optimization of the products that are built towards supporting the future of the payments industry.

Much of the functionality provided by Adaptive Payments is available in newer solutions that fully support the latest in consumer experiences from PayPal, such as mobile optimization and One Touch. However, Adaptive Payments is still the best solution for a small set of use cases, which is why we will continue to offer it as a limited release product for select partners.

Existing applications and Adaptive Payments users

For existing users of Adaptive Payments, your applications will continue to work during this process, and you will not experience any disruption in service. With that said, we will be working hard in the coming months to provide migration guides, advice, and support for moving existing developers towards integrating Braintree or the PayPal REST APIs, which will be continually updated to support any modern features or payment methods that should arise.

If you are not currently using Adaptive Payments for your payment integration, it is not recommended that you create a new service with Adaptive Payments as the payment integration mechanism.

Stay tuned for updates.

Building the Next Step in Payment Tutorials with Stack Overflow Docs


At PayPal Developer, we are constantly looking at new ways to expand our outreach into the community to provide the solutions that developers need, where they choose to be. This is why we work within different external communities, such as Stack Overflow to help with technical integrations, and Github for much of our external developer code offerings and open source projects.

We’re happy to announce that we have partnered with Stack Overflow for the launch of a new project called Stack Overflow Documentation. The aim of the Stack Overflow documentation project is to build a community around the process of creating great documentation, not by simply copying our documentation to another place, but by working with the community to build the documentation, examples, and integrations that developers want and care about. We’ve started by adding some examples based off of common questions that we receive frequently.

Come take a look at the initial documentation and examples we have on Stack Overflow Docs and make suggestions for integrations that you want to see. We’re going to be working hard to help deliver the content that you want to see, and we would love for you to be a part of this with us by contributing examples and topics for things that you built out, by requesting new topics for us to write about, or by improving the samples that we already have up on the site if something just doesn’t make sense or should be revised.

We look forward to working with everyone in our community to build the examples that you all care about.

Dates Revised for Security-Related Changes


We’ve revised some of the dates originally published in the Security-Related Changes Required to Avoid Service Disruption post from earlier this year.

The dates have been revised in order to give merchants additional time to plan for any necessary changes and to give developers additional time to update their integrations.

The dates in the original post reflect the current deadlines. In summary, here are the date revisions:

  • The TLS1.2 Upgrade date moves to June 2017.
  • The HTTPS for IPN Postback date moves to June 2017.
  • The SHA-256 Upgrade dates: Merchants must be compliant by September 30, 2016 as we will begin our permanent upgrade of the remaining endpoints in October 2016. Take action by June 17, 2016 to verify if your system is SHA-256 compliant.
  • The SFTP Server move dates remain the same.
  • The API Authentication Credential Certificate dates remain the same.

Developers should continue to reference the 2017-2018 Merchant Security Roadmap microsite for all the latest details and up-to-date information regarding these security changes.

Adam Colson

Author: Adam Colson

About the author: Adam is a Product Manager at Braintree | PayPal, focusing on the PayPal developer experience since August 2015. When Adam isn’t helping to enable global e-commerce through APIs, he can also be found hacking away at the Internet of Things or tinkering in his garage.

@adamc | LinkedIn

Security-Related Changes Required to Avoid Service Disruption


REVISED May 12, 2016Please note that some of the deadlines have changed since this post was originally published. This post reflects the latest deadline dates for security updates.

Beginning in early 2016, PayPal will introduce a number of security-related product updates.

These updates are part of an industry-wide initiative to improve security standards. Some of these updates, like the TLS upgrade, are mandated by the PCI Security Council and are required by every website that transmits or processes cardholder data.

Merchants and developers may have to update their integrations in order to be in compliance and ensure that their applications continue to function as expected.

For PayPal customers, these updates include:

TLS 1.2 Upgrade

The most secure protocol for sharing information on the web today is Transport Layer Security (TLS) version 1.2. PayPal is enabling support for TLS 1.2 for all secure connections and in 2016 will start requiring its use. You will need to verify that your environment supports TLS 1.2 and if necessary make appropriate updates. PayPal is updating its services to require TLS v1.2 for all HTTPS connections in June of 2017. After that time, all TLS v1.0 and TLS v1.1 API connections will be refused.

Learn more

IP Address Update for PayPal SFTP

If your integration is set-up to systematically exchange files with PayPal’s Secure FTP Reporting / Batch Servers, please note that the IP addresses for these servers are changing. If your integration is hardcoded to the current IP addresses, you will need to upgrade accordingly. You must act by April 14, 2016.

Learn more

IPN Verification Postback to HTTPS

If you are using PayPal’s Instant Payment Notification (IPN) service, you will need to ensure that HTTPS is used when posting the message back to PayPal for verification. After June of 2017 HTTP postbacks will no longer be supported.

Learn more

Merchant API Credential Upgrade

The certificates issued by PayPal as API Credentials for use with the Classic API are being upgraded to SHA-256 signed 2048-bit certificates. If you currently connect to PayPal using Certificate API Credentials, you will need to have a new certificate issued and start using it for all API requests. Depending on when your certificate expires, you will have to upgrade between Jan 31, 2016 and Jan 1, 2018.

Learn more

SSL Certificate Upgrade

PayPal is in the process of upgrading the SSL certificates used to secure our web sites and API endpoints. These new certificates will be signed using the SHA-256 algorithm and VeriSign’s 2048-bit G5 Root Certificate. You will need to ensure that your environment supports the use of the SHA-256 signing algorithm and discontinue the use of SSL connections that rely on the VeriSign G2 Root Certificate. This action must be taken by June 17, 2016 in order to avoid any disruption of service.

Learn more

PayPal SDK Updates

For developers using one of PayPal’s SDK libraries, depending on the runtime environment and version your application uses, a code change or SDK update may be required in order to enable TLS v1.2. Java 6 u115 b32, Java 7 or Java 8 (preferred) and Android 4.x environments require TLS v1.2 to be enabled in order to maintain functionality.

If you’re using one of PayPal’s REST SDKs, the best practice is to stay up to date with the latest SDK version and latest versions of the code libraries required by the PayPal SDK. PayPal provides server and client SDKs for Java, .Net, PHP, Python, Ruby, Node.js, Android, and iOS. Detailed test instructions can also be found at

Developers should reference the 2017-2018 Merchant Security Roadmap microsite for all the latest details and up-to-date information regarding these security changes. You can also visit the PayPal Developer site for more information on PayPal security guidelines and best practices.

Adam Colson

Author: Adam Colson

About the author: Adam is a Product Manager at Braintree | PayPal, focusing on the PayPal developer experience since August 2015. When Adam isn’t helping to enable global e-commerce through APIs, he can also be found hacking away at the Internet of Things or tinkering in his garage.

@adamc | LinkedIn

Swagger is Now a Part of PayPal’s Future


On November 5th, the Linux Foundation announced a new collaborative project, the Open API Initiative. PayPal is proud to be one of the founding corporate members. This expands our relationship with the Linux Foundation and the open source world, as we are already members of the Node Foundation. This collaborative project establishes an open governance structure for moving the Swagger specification into the future, with corporate resources supporting the specification.


If you’ve followed Swagger’s story in recent years, you’ll know that in 2014, the project’s brand was bought by SmartBear (an API testing tool company, know for SOAPUI). As it turned out, this complicated things somewhat, from a trademark standpoint, for some adopters of Swagger’s open source standard.

The folks at SmartBear wanted to do the right thing for the Swagger open source community, so they’ve contributed the specification format to the Linux Foundation. The specification format will be referred to as the Open API Definition Format (OADF), which is essentially a brand-free synonym for Swagger.

PayPal was contacted by SmartBear and the Linux Foundation at the inception of the Open API Initiative. We had previously established a relationship with Swagger maintainers, as we’ve had numerous 2015 internal initiatives utilizing Swagger for API definitions. We were excited to join other leaders in the API space as part of the founding group of this collaborative project.

In discussions so far, it’s clear that all members involved are interested in supporting open source collaboration, and moving the Swagger specification forward without hindrance. The most exciting part is hearing that many member companies are planning to dedicate development resources toward contributing to Swagger open source projects.

PayPal, Braintree and Venmo are shifting more internal and external API initiatives and development resources toward utilizing Swagger, and we look forward to continuing to contribute to existing projects, and hopefully releasing some of our own.

PayPal has had a long-standing commitment to open source through our many iterations of APIs, including our latest REST APIs/SDKs and Braintree’s SDK. We understand that our SDKs don’t cover every language available, and that there are some great open source codegen products available for API clients, when a Swagger definition is provided.

We’re committed to delivering Swagger definitions for our APIs to our developer community in 2016, stay tuned for more information.

Jason HarmonAuthor: Jason Harmon

About the author: Jason is the former head of the API Design team at PayPal, helping development teams design high quality, usable APIs across the platform. He blogs at, and has a Youtube channel API Workshop (

Feature Release: Credential Rotation on Developer Portal to Enhance App Security


At PayPal, we take security seriously. Since the client-secret in the API world is akin to your password in the web world, it is a well-known security best practice to regularly change the client-secret that your application uses. Regularly scheduled changes to the client-secret keeps the attackers at bay and ensures that your app is less vulnerable to being compromised.

To simplify the credential rotation process, we have now enabled this capability as a self-service feature on the developer portal. We hope that this feature will provide greater flexibility to our developers in rotating credentials per their own schedule.

Lifecycle of a client-secret at PayPal

Continue reading

Webhooks for Payouts


Today, we are delighted to launch the much awaited Webhooks support for Payouts. Payouts is a highly convenient mechanism for processing mass payments across multiple accounts in a single API call. With this feature, you can now initiate a payout transaction and receive notifications on your webhook URLs for Processing, Success and Denied scenarios.

Merchants and Developers can now subscribe and receive notifications for the following events

  1. Payment payoutsbatch processing
  2. Payment payoutsbatch success
  3. Payment payoutsbatch denied

Payouts Processing

Continue reading