Monthly Archives: June 2015

PayPal’s API Style Guide


Jason HarmonAbout 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 (

Since 2013, PayPal has been developing a new generation of APIs, using REST semantics. While our public API developer community has seen the outward effects of this, internally we’ve been using the same strategy. Since 2013, we’ve defined most of the PayPal platform using REST APIs.

As part of the team guiding this engineering-wide project (we call it PPaaS aka “PayPal as a Service”), our API Design team has had the privilege to work with a huge number of development teams. We consult with development teams on API design to ensure the broadest consistency, sound usability, and a myriad of other concerns.

During the process of collaborating on hundreds of API designs, we’ve developed a detailed set of internal standards. With the size of our team it’s important to provide some level of detail. This provides our developers building APIs clear guidance. However with all the detail we’ve provided, it can get a little tough to get started learning what good API designs look like. In an attempt to capture the basics, and provide an overview of our Standards, we’ve composed our API Style Guide. Rather than keeping this within our internal developer community, we removed any internal or proprietary references, and made it something anybody could use as a set of API design guidelines. A handful of other organizations, such as Heroku and The White House have shared their standards as well.

The hope is that more organizations that are passionate about APIs will share their design guidelines. This can only improve the consistency of the API space. While there are many books on the subject, looking at popular APIs is often the first place new API developers get started. Often this leads to guessing why a design works the way it does. By providing Standards or a Style Guide, new API developers can get a better sense of the rationale behind a functioning design.

We’ve published PayPal’s API Style Guide on Github. Most of the examples provided are based on our REST APIs, which you can find out more about on

PayPal SSL Certificate Changes


To continue our policy of ensuring the highest level of security for our merchants, developers, and consumers, PayPal is making upgrades to the SSL certificates on all web and API endpoints.

Merchants and developers will need to ensure that all required upgrades are implemented, as described below, to prevent an outage to your payment processing, Instant Payment Notifications (IPN) services, or other API service connections.

Why are These Changes Needed?

Due to security concerns over advances in computing power, the industry is phasing out 1024-bit SSL certificates (G2) in favor of 2048-bit certificates (G5), and is moving towards a higher strength data encryption algorithm to secure data transmission, SHA-2 (256) over the older SHA-1 algorithm standard.

Since Chrome is deprecating support for SHA-1 by the end of 2015, and all support for SHA-1 will be deprecated by the end of 2016, we need to act soon to implement these changes.

During the upgrade, we will ensure that all SSL certificates meet the following standards:

  • Discontinue support for secure connections that require validation with the VeriSign G2 Root Certificate; only validate with the VeriSign G5 Root Certificate.
  • Use a stronger algorithm by upgrading from SHA-1 to SHA-2 (256).

Who will be Impacted?

The main impact of these changes is to merchants and developers with an integration that does not use the new VeriSign G5 Root Trust Anchor, or those whose hardware / software does not support the SHA-256 signing algorithm.

If you are unsure if you fall into one of these categories, please contact the company / developer who assisted with your original integration. Typically these integrations may come through a 3rd party cart system (e.g. Zen Cart), hosting company (e.g. GoDaddy), or individual developer.

Please click here for a complete rollout schedule for the upgrades on PayPal.

How to Update to Prevent Service Outage

To prepare for these changes, please use the checklist below to ensure everything has been upgraded completely:

  • Talk to the technical contact or 3rd party partner that you used to create the checkout.
  • Save the VeriSign G5 Root Trust Anchor in your keystore.
  • Upgrade your environment to support the SHA-256 signing algorithm.
  • Perform end-to-end testing of the integration against the Sandbox / Payflow Pilot environment (including Instant Payment Notifications (IPN), Payment Data Transfer (PDT), and Silent Posts).

Upgrading is not required if you are using Website Payments Standard (the “Buy Now” buttons), or Payflow webapps only.

Testing Your SSL Certificate Upgrade

Any tests that are currently run against PayPal Sandbox endpoints will require a VeriSign G5 root certificate, so you can test your upgrades by making requests against the Sandbox environment by using the following steps:

Testing Your SHA-256 Algorithm Upgrade

SHA-256 testing is available as of April 8th using the Payflow Pilot, or testing will also be available against the PayPal Sandbox in Q1 2016.

Need More Information, or Running into Problems Upgrading?

For technical upgrade information, please see the merchant security system upgrade guide.

Every integration is unique, and unexpected issues can always arise. If you are running into problems with the upgrade, PayPal MTS is available to assist with any specific errors or problems that might arise.