Category Archives: API

API Style Guide and Patterns: The Evolutionary Journey Continues

By

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.

Principles

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

By

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:

{
    'intent':'sale',
    'redirect_urls':{
        'return_url':'http://localhost:3000/process',
        'cancel_url':'http://localhost:3000/cancel'
    },
    'payer':{
        'payment_method':'paypal'
    },
    'transactions':[{
        'amount':{
            'total':'10',
            'currency':'USD'
        },
        'payee':{
            'email': 'payee@test.com'
        },
        '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!

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

By

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 v.zero 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 v.zero 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.

TLS 1.2 Upgrade Technical White Paper

By

REVISED May 12, 2016Please note that the deadline for the TLS update has been moved out to June 2017

As a leader in Financial Technology, PayPal’s mission is to provide simple, affordable, secure and reliable financial services and digital payments. To accomplish this mission, we constantly evaluate our security posture – which includes complying with industry standards, laws and regulations – to create an environment our merchants and consumers can trust.

Beginning June 2017, PayPal will begin the process of discontinuing support for TLS 1.0 and 1.1, meaning that all communications with PayPal API (including SDK) must use TLS 1.2.

You can read more about PayPal’s official position on mandating the TLS 1.2 upgrade, the rationale for the upgrade as well as resources for merchants and developers to help them through the upgrade process by downloading the Foundation for June 2017 TLS 1.2 Upgrade Technical White Paper.

For information on all the security-related updates that are required this year, visit the 2016-2017 Merchant Security Roadmap Microsite.

Swagger is Now a Part of PayPal’s Future

By

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.

swagger1

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 apiux.com, and has a Youtube channel API Workshop (https://www.youtube.com/channel/UCKK2ir0jqCvfB-kzBGka_Lg).

The New API Transactions Dashboard

By

The new Transactions dashboard, launched recently, is also referred to as “API call history”. It provides histories of the transactions (API calls) made by applications in the sandbox and live environments. It provides details such as the date of the transaction, type of the transaction, status, amount, as well as the details of the API call, such as the request and response messages.

The new dashboard has many features:

  • Displays history of all PayPal REST APIs.
  • Shows API call details like HTTP status code, request, response and headers to help with diagnostics.
  • Provides the ability to browse and find details quickly through pagination and filters.
  • Has 10x better performance.

Live Transactions Dashboard

An example of the live transactions dashboard is shown below

Live Transactions Dashboard

The live dashboard displays the following:

  • HTTP status
  • Resource URI that was invoked
  • Transaction ID
  • Transaction Date

You can browse transactions for all your applications and filter transactions based on the application name. The dashboard also gives you the ability to view the details of a transaction. By clicking a transaction in the table above, you will see a popup like the below:

Live Transactions Metadata

It has the following fields:

  • Metadata – Metadata about the transaction Request
  • HTTP request, including headers Response
  • HTTP response, including headers

Sandbox Transactions Dashboard

An example of the sandbox transactions dashboard is shown below:

Sandbox Transactions Dashboard

The sandbox transaction dashboard is similar to the live transaction dashboard, except that you can also filter the transactions based on the sandbox account. Since a developer can have multiple sandbox accounts associated with multiple sandbox applications, filtering on the basis of either a sandbox account email or an application can help you quickly find the transaction you are looking for.

Miscellaneous Information

The new dashboard can be accessed via the following links:

Rahul PanjrathAuthor: Rahul Panjrath
About the author: I am Software Engineer @Braintree|PayPal since April 2014, part of the team responsible for https://developer.paypal.com. Coding is my passion and I love to break things daily ;). I graduated from San Jose State University and I have been in the software industry coding for almost 9 years and I am still learning new things everyday. That’s the best part which makes me love the work I do. I specialize in web programming, REST APIs development, TDD etc.

I can be reached at:

PayPal’s API Style Guide

By

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 apiux.com, and has a Youtube channel API Workshop (https://www.youtube.com/channel/UCKK2ir0jqCvfB-kzBGka_Lg).

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 developer.paypal.com.

Webhooks for REST APIs launched

By

(By Joe Nash & Alberto López)


PayPal’s latest addition to the roster of products taking advantage of PayPal REST API technology gives developers easier access to notifications of payment activities, such as payment status updates. PayPal webhooks are now available, and not only do they enable similar functionality to that of the IPN available in the Classic APIs, but they provide additional functionality to ease development and create innovative new products.

What is a webhook?

When we discuss webhooks, we refer to three key actors:

  • Webhooks: A webhook takes the form of a POST request to a URL that you set via your PayPal account. When a payment is made, or the status of a payment changes, the POST request is triggered, sending an event. This allows you to see and work with payment updates in real time. Webhooks can be created, updated, listed and deleted all through your PayPal account.
  • Events: An event contains the details about the payment update, including: the time of payment authorization or the amount of a payment or refund. Past events are searchable, and can also be resent in a webhook. There are multiple event types.
  • Event types: Event types can be selected to only cause the triggering of webhooks for specific payment updates and information, allowing you to choose to receive POST requests about the information that is important to you and your product.

Through these three actors, developers can manage operations that happen during the transaction lifecycle. Developers can list all of the event types subscribed to by a given webhook, perform more focused searches such as searching for webhooks by event type, and the API itself can be used to retrieve webhook events.

What operations are available using webhooks?

Webhooks provide some interesting functions for developers:

What are the differences between Webhooks and IPN?

At first glance, the differences between Webhooks and IPN used in the Classic API are subtle. What makes webhooks desirable over IPN is their sheer customisability versus IPN:

  • Whilst IPN did allow for the configuration of different IPN listener’s for different transactions, the IPN listener had to be predefined in the PayPal account. Further, it could only be modified through the PayPal account, and by default all refunds notify to this listener. With Webhooks you will be able to create different webhooks via the API for managing different event types (an authorization created, or voided or refunded), and modify each of them using an API REST call.
  • Webhooks enable the retrieval via API of any webhook event that was unable to be collected in the initial triggering of the webhook. In contrast, IPN events were only accessible via the PayPal account.
  • Webhooks have the important property of real time event notification, whilst with IPN, some delays could be experienced.

It is clear that webhooks give distinct advantages versus IPN; they are more flexible, versatile and can be used in real time. Let’s see how they work.

How do Webhooks work?

To use the webhook API in the Sandbox, first do the following:

  1. Go to the My REST apps page.
  2. Create an application, if you haven’t done so already.
  3. Add a webhook URL (the maximum number of webhooks is 10).
  4. Subscribe to the event types of interest. As we said before, you can also choose to manage webhooks, events, and event types through the Webhooks API.

Getting the bearer token:

Request

curl https://api.sandbox.paypal.com/v1/oauth2/token
\ -H "Accept: application/json" 
\ -H "Accept-Language: en_US" 
\ -u "<Client-Id>:<Secret>" 
\ -d "grant_type=client_credentials”

Response

{ "scope": "https://api.paypal.com/v1/payments/.*
https://api.paypal.com/v1/vault/credit-card/
https://api.paypal.com/v1/vault/credit-card/.*",
"access_token": "EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBVTTTWxVvgmsG",
"token_type": "Bearer",
"app_id": "APP-6XR95014BA15863X",
"expires_in": 28800
}

Creating the webhook via API

Request

curl -v POST https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H 'Content-Type:application/json' \
-H 'Authorization: 
        Bearer EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBVTTTWxVvgmsG' \
-d '{
   "url": "http://www.yeowza.com/paypal_webhook",
   "event_types": [
       {
           "name": "PAYMENT.SALE.REFUNDED"
       },
       {
           "name": "PAYMENT.CAPTURE.REFUNDED"
       }
   ]
}'

Response

{
"id":"0E842532SB505363J",
"url":"https://www.mysite.com/paypal_webhook",
"event_types":[
    {
        "name":"PAYMENT.SALE.REFUNDED",
        "description":"A sale payment was refunded"
    },
    {
        "name":"PAYMENT.CAPTURE.REFUNDED",
        "description":"A capture payment was refunded"}
    ],
"links":[
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"SELF",
     "method":"GET"
    },
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"UPDATE",
     "method":"PATCH"
    },
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"DELETE",
     "method":"DELETE"
     }
]
}

After making a payment, you’ll receive in your webhook (https://www.mysite.com/paypal_webhook) an event type with the information of the event type:

{
 "id": "WH-0AF57170N8121644E-6VF27453LH2982421",
 "create_time": “2014-09-25T21:41:28Z",
 "resource_type": "authorization",
 "trigger_event": "PAYMENT.AUTHORIZATION.CREATED",
 "summary": "A payment authorization was created",
 "resource": {
   "id": "0MW879906U0874649",
   "create_time": "2014-09-25T21:39:15Z",
   "update_time": "2014-09-25T21:39:17Z",
   "state": "authorized",
   "amount": {
     "total": “10.00",
     "currency": "USD",
     "details": {
       "subtotal": “10.00"
     }
   },
   "parent_payment": "PAY-0AB48420EF007493KKQVUMBY",
   "valid_until": "2014-07-24T21:39:15Z",
   "links": [
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649",
       "rel": "self",
       "method": "GET"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649/capture",
       "rel": "capture",
       "method": "POST"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649/void",
       "rel": "void",
       "method": "POST"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               payment/PAY-0AB48420EF007493KKQVUMBY",
       "rel": "parent_payment",
       "method": "GET"
     }
   ]
 },
 "links": [
   {
     "href": "https://api.sandbox.paypal.com/v1/notfications/
             webhooks-events/WH-0AF57170N8121644E-6VF27453LH2982421",
     "rel": "self",
     "method": "GET"
   },
   {
     "href": "https://api.sandbox.paypal.com/v1/notfications/
             webhooks-events/WH-0AF57170N8121644E-6VF27453LH2982421/
             resend",
     "rel": "resend",
     "method": "POST"
   }
 ]}

In our webhook event, we get all of the information, coupled with useful links, given by the event type. From here, we can perform some operations on the data, update our databases, or launch a process after ensuring the process is done.

Creating and Processing an order using the PayPal REST APIs

By

I am happy to announce that we’ve added the ability to create and process an order to the PayPal REST APIs.

Getting Started

To get started, follow this tutorial. To create and process an order, you can use the following steps:

  1. Create the order.
  2. Get customer approval.
  3. Execute the order.
  4. Authorize an order.
  5. Capture an order.

Creating a PayPal Order indicates that the buyer has consented to the purchase but does not place the funds on hold. After creating the Order, you can capture the order directly without any additional authorization, or you can create an authorization API call to place funds on hold until you are ready to capture. Since the order does not place funds on hold, it is advised that you follow the second approach and create an authorization instead of capturing an Order directly.

This technique is often used by merchants who accept orders for varying items, some of which may not be available for shipment at the time the order is placed (for example: a website that allows customers to buy multiple items from different retailers with different shipping dates, managing the retailer billing as each item ships). Subsequent basic authorizations are made as the items become available. These authorizations ensure that the customer still has the funds available to purchase each item. You can make up to 10 basic authorizations for each Order.

An order is valid for 29 days. Within this period, you can request one or many authorizations to ensure the availably of funds. The sum of the total open authorizations can’t exceed 115% or $75 (whichever is less) of the amount provided to PayPal when the order was created.

To Infinity and Beyond!

Payments have always been very exciting to us and we look forward to see what cool applications you build with these new REST APIs.

As always your feedback is welcome and we look forward to find ways to improve and serve you better.