Tag Archives: APIs

New REST API Feature: Setting a Receiver for Payments

By and

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!

Swagger is Now a Part of PayPal’s Future

By and

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 and

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 and

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.

PayPal SSL Certificate Changes

By and

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.

Subscriptions are Now Available in the PayPal REST APIs

By and

As of today, I am happy to announce that subscription models (what we call billing plans and agreements) have launched as our newest piece of functionality in the PayPal REST APIs.

This long awaited feature will allow you to not just process one time payments, but instead set up and modify entire recurring payment cycles, including the ability to incorporate trial periods for greater product control.

How it Works

While there is a lot of new functionality to play with in this API release, let’s start by taking a look at how to get to the point of starting to bill a customer on a monthly basis, and also include a trial period for the product for people to try before they buy.

In its simplest form, how we make a subscription model work is a two step process:

  1. Create a Billing Plan: Basically all you’re doing here is creating the billing template that you can use to subscribe users to a particular billing plan.
    Tip: You can have multiple billing plans set up at the same time.
  2. Create a User Billing Agreement: Once you have the billing plan template in place, you can then use that template in the payment process to set up a recurring payment cycle for a user, such as monthly.

That’s pretty much the gist of it, create a billing plan, then assign a user to a particular plan (called a billing agreement) when you push them through to pay. Let’s dive a little bit deeper into these features, and see how each piece works.

Creating a Billing Plan

Let’s say we run a “Fruit of the Month” club, and we sell monthly subscriptions to ship a new assortment of unique fruits to people monthly. For new customers, we also offer a trial period where you can have the first month free, to take a look at the quality of the product. The request to the billing plan API would look something like this:

    curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-plans \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
    "name": "Fruit of the Month",
    "description": "10 Pound Box of Fruit",
    "type": "fixed",
    "payment_definitions": [
        {
            "name": "Standard Package",
            "type": "REGULAR",
            "frequency": "MONTH",
            "frequency_interval": "2",
            "amount": {
                "value": "50",
                "currency": "USD"
            },
            "cycles": "12",
            "charge_models": [
                {
                    "type": "SHIPPING",
                    "amount": {
                        "value": "8",
                        "currency": "USD"
                    }
                },
                {
                    "type": "TAX",
                    "amount": {
                        "value": "4",
                        "currency": "USD"
                    }
                }
            ]
        },
        {
            "name":"First Month Free Trial",
            "type":"TRIAL",
            "frequency":"MONTH",
            "frequency_interval":"1",
            "amount": { 
            "value" : "50",
            "currency" : "USD"
        },
        "cycles":"1",
        "charge_models": [
            {
                "type":"SHIPPING",
                "amount": { 
                    "value" :"8",
                    "currency" : "USD"
                }
            },
            {
                "type":"TAX",
                "amount": {
                    "value" :"4",
                    "currency" : "USD"
                }
            }
        ]
    }],
    "merchant_preferences": {
        "setup_fee": {
            "value": "1",
            "currency": "USD"
        },
        "return_url": "http://www.fruitofthemonth.com/complete",
        "cancel_url": "http://www.fruitofthemonth.com/cancel",
        "autobill_amount": "YES",
        "initial_amount_fail_action": "CONTINUE",
        "max_fail_attempts": "0"
    }
}'

Once you create the billing plan, you’ll get a JSON response back, which will include an ID referencing back to the billing plan. This is what we’re going to use when we push a user through to the payment step to reference what billing plan we want them signed up to, called a billing agreement.

Subscribing a User to a Billing Agreement

Next, let’s say a customer has come to our site and wants to subscribe to the “Fruit of the Month” club. She picks the plan that she wants to be a part of (let’s say a 10 pound box of fruit) and is subscribed using a billing agreement (essentially just subscribing a user to a billing plan) that we just set up by pushing her to PayPal to use her account.

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
    "name": "Main Subscription",
    "description": "Fruit of the Month Subscription",
    "start_date": "2015-02-19T00:37:04Z",
    "plan": {
        "id": "P-0NJ10521L3680291SOAQIVTQ"
    },
    "payer": {
        "payment_method": "paypal"
    },
    "shipping_address": {
        "line1": "My Business",
        "line2": "1665 Biscayne rd",
        "city": "Miami",
        "state": "FL",
        "postal_code": "33141",
        "country_code": "US"
    }
}'

As you can see from the sample, we are sending a user through a standard PayPal payment method, passing in the new “plan” object within the request payload. That will reference the ID that we gained back when creating the billing plan above. We will get back a redirect URL to forward the user to in order to sign in to their PayPal account.

That’s pretty much it for our simple example. Between a billing plan and the user billing agreement, you can create any number of subscription scenarios for your customers.

Going Further

We’ve obviously just began to touch on all of the functionality that’s available to us with the new billing plan / billing agreement APIs. We can go further with mechanisms to suspend and revoke billing agreements, update parts of billing plans, and a number of other scenarios.

As you build out your subscription system, you can dive into more detail about the capabilities on the REST API docs.

Open sourcing genio

By

The PayPal Developer team strives to build SDKs and Tools that make it easy for developers and integrators to work with PayPal APIs. Our SDKs are designed with a shared core component that handles cross cutting concerns and different API specific components that contain model classes and utility wrappers.

When we sat down to write the API specific components, lazy developers that we are, we looked out for code generation tools that we could bootstrap on. We found a few open source code generators such as java2wsdl but none that had support for custom templates or could generate classes in multiple languages. So we sat down to write genio (pronounced ‘genie-oh’), our very own code generator that we are happy to now open source.

genio is a pluggable code generation system that can parse various API specification files into a generic model. The parsed model is pumped through a set of templates to generate full fledged classes with class documentation from the API specification file and custom logic for plugging into our core SDKs. The SDKs that you see on GitHub have all been generated using the tool. genio has helped us upgrade our SDKs and other tools within minutes of a new release. The upgrade is often triggered by a git commit hook on the API repo. When we released the new REST APIs back in February, we wrote a new WADL parser that produced genio compliant model objects and with a few minor tweaks to our templates, we were ready with the first version of our REST SDKs. Subsequently we switched to using the Google discovery format and it was a trivial task for us to start generating the SDKs using the new specification format. In all, the current release has parsers for WSDL, WADL and the Google discovery format. We will follow up this release with API documentation generation features and support for JSON schema version 4.

genio-blocks

How genio can be useful to you

What has been useful to us is potentially useful to other developers as well. When we saw other groups in eBay Inc. show interest in genio, we plugged new templates to the genio parser to build API references, testing tools, API explorers and so on. And now, we are open sourcing it, hoping that the developer community can benefit as well and also contribute with enhancements.

Any project that implements or consumes APIs can use genio to generate service stubs, client stubs, testing tools etc. genio is being released as two ruby gems:

  • genio-parser that parses service specification files into a generic model and
  • genio that provides a set of templates and uses genio-parser to generate code.

The client templates shipped with genio in this release generate client stubs that can be plugged directly into our core SDKs. If you have a preferred service framework, you can write new templates that are specific to your framework. You can contribute new templates to genio or add support for new specification formats in genio-parser. We will be thrilled to accept those that target widely used open frameworks / API specification formats.

Look at the genio samples repository for example code generated using genio. Do look out for our next blog post that will tell you how genio can be extended to suit your needs.

Temboo and the PayPal API

By and

temboo_vaughn_bioAbout the author: Vaughn Shinall does business development for Temboo, working to connect developers, web services, and more for the next generation of applications.

Want to to use the PayPal and several other APIs without spending hours reading documentation? Then you should know about Temboo. Temboo provides normalized access to over 100 APIs, saving you the effort of learning how to use each one. And that means more time to experiment with new APIs and to focus on the creative side of development instead of reinventing the API wheel. The Temboo

Library contains over 1800 special methods called Choreos (as in choreography) for a wide range of APIs, and in this post I’ll walk you through how to use Temboo to check an account balance with the PayPal API. Once you’ve learned how to use this Choreo, you’re ready to use all our other Choreos for PayPal and every API in our Library–that’s the power of Temboo.

Step 1 – Get A Temboo Account

Go to Temboo.com and enter your email address on the home page. After confirming your email address and setting up an account name and password, you’ll have a free Temboo account with access to everything in our Library.

Step 2 – Find the Choreo in Our Library

temboo_1 Be sure you are logged into your account, and go to our Library page. On the left hand side you’ll see a list of all our APIs. Find PayPal, open the Merchants bundle, and select the Get Balance Choreo.

Step 3 – Test Run A Choreo From Your Browser

temboo_2 On the Choreo page you’ll see all the required inputs for this action. Scroll down the page to see information on the output the API returns for the Choreo, sample code (more on this later), and a description of the Choreo. Back at the top of the page, you can enter the inputs and any optional inputs you choose. In this instance, I’m entering the password, signature, and username from my PayPal developer test account and setting the optional input to 1, indicating that I’m testing this Choreo against the PayPal sandbox. Now I’m ready to run this Choreo from my browser by clicking the Try It Out button. temboo_3 After the Choreo has run, you’ll see that the Output box now shows what the PayPal API’s output. My account balance is zero in US dollars. temboo_4 And immediately below that, you’ll see that the Sample Code has now been updated with all the inputs you entered for this Choreo run. This is code that you can copy and paste into your IDE to incorporate a Choreo directly into your application. (Rather than passing my PayPal password, signature, and username through the code, I’ve used Temboo Credentials to wrap them into one credential called ‘PayPalTest’.) Note that you can also select the programming language that you want the sample code in. temboo_5

Step 4 – Run the Choreo from your IDE

Download the Temboo SDK in the language of your choice, and add it to your IDE. (Our tutorials provide detailed instructions.) Then paste the sample code into your project. For this example I am using our Java SDK and an eclipse, so my code looks like this: temboo_6 Note that the first line of code starts my Temboo session by supplying the following Temboo credentials: my account name, the name of the Temboo Application Key I’m using, and the Application Key itself. (Your Application Keys can be found and managed here.) Then I add the following line to have the API output appear in my console:

System.out.println(getBalanceResults.get_Response());

Now I’m ready to run the project, and I get the following output in my console:

L_AMT0=0.00&L_CURRENCYCODE0=USD&TIMESTAMP=2013-07-01T20:05:11Z
&CORRELATIONID=a2b15b35cf174&ACK=Success&VERSION=56.0&BUILD=6561328

And that’s it! Now you know how to use Temboo to run any of the 21 PayPal Choreos–or the hundreds of other Choreos in our Library. Check out Temboo today to see what you can build with the PayPal API.

Auth / Capture Payment Support Now Available in the New RESTful APIs

By and

Today I am very happy to announce the launch of auth / capture support in our new RESTful APIs! With this new support mechanism, you will be able to hold a portion of funds from a user account (auth) for a period of time before processing the payment and transferring the funds (capture).

An applicable use case for something like this would be if you have a business that loans out products. When the user receives the product the charge can put on the customer’s credit card, and only when they return it do you process the funds. Using this mechanism, you can ensure that the funds will be available when processing them. Of course, there are many other use cases for a system like this.

How long can you capture the funds for?

One of the first questions that you might have about this new API feature is, “How Long will I be able to hold money on a user’s account for?”. The short answer to that one is that an authorization will be guaranteed to be available for 3 days (guarantee that the funds will be locked on the funding source), but you will be able to attempt authorizations for a period of 29 days.

How do you use it with the new APIs?

To get things started, if you’ve never worked with the new RESTful APIs, I would suggest starting with a little bit of background on how they work (it’ll make this a lot easier). Here are some links for that:

Now that we have that covered, let’s get into a few specific differences in processing a payment versus making an authorization call. First off, when you are authorizing a payment you will be making a request to the same API endpoint as you would if you are making a payment:

https://api.sandbox.paypal.com/v1/payments/payment

The only other difference in payment versus auth is in the POST payload that you send through with the request. When you are making a payment, you would set the “intent” key in the POST body to “sale”, to indicate a payment. If you are processing an authorization payment, then you would instead set “intent” to “authorize”, like so:

"intent":"authorize"

After you make that request, you will receive a JSON response back from PayPal indicating the success or failure. There are a few key things about the response structure that are important to note for processing the payment and verifying its success: * id: This is the unique payment identifier that you can use to later look up information or process the payment. * state: On success, this will be set to approved, stating that the funds are locked. * links (under the transactions key): This will be a series of HATEOAS links to provide you with logical next steps in the auth/capture process. With that said, let’s take a quick look at those HATEOAS links that are returned to us:

"links":[
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S",
    "rel":"self",
    "method":"GET"
  },
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/capture",
    "rel":"capture",
    "method":"POST"
  },
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/void",
    "rel":"void",
    "method":"POST"
  },
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-0R831151JU007784NKGSU2SA",
    "rel":"parent_payment",
    "method":"GET"
  }
]

These links provide the next actions that you can take with the REST APIs, with information on how to make the request. Based on their “rel” tag, they include: * self: Look up information on the auth request * capture: This is the request to capture the payments (part 2 in the 2 step auth/capture process) * void: Void the payment * parent payment: Look up the payment resource itself With those links, you’ll have everything you’ll need to do to build proper auth/capture support. If you don’t want to work with the HATEOAS link structure, then you can set up the capture / payment lookup yourself using the same API endpoints and data that are available in those links. More information on all of that is available in the

official documentation for auth/capture support.

More Features Coming Soon! As we endeavor to create better RESTful APIs for our commerce developers, having feature parity between the

REST and classic APIs is a very important future step for us. With that in mind, you will see continuous releases that add in the support that our developers are asking for.

Classic API Application Creation Being Migrated Tonight

By and

Starting on May 13th, 2013 (6pm PST), the creation of new applications for our Classic APIs on x.com will be suspended for 48 hours while the system is migrated to its new home on developer.paypal.com.

During this time, you will not have access to submit a new application or manage your existing applications. Your current application IDs will not be impacted by the migration and will be available post-migration at the new location.

Please check back after May 16th for the new location of the application management tool on developer.paypal.com.