Tag Archives: announcements

Building the Next Step in Payment Tutorials with Stack Overflow Docs

By and

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.

Security-Related Changes Required to Avoid Service Disruption

By

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 https://github.com/paypal/TLS-update.

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

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

By and

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

By and

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

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.

Behold SXSW submission voting is upon us

By

Upon the hallowed grounds that is the Austin Convention Center there is but no event that stops the world of tech like South by South West. SXSW where the industry elite gather to converse, present and partake of all things Music, Film and Interactive in an assembly of ideas and thinking covering futuristic ideology.

SXSW founded in 1987 the conference is now in its Twenty Seventh year and has become one of the lighthouses for the technological world in years of late as the lines between online and offline have continued to blur particularly with the onset of Augmented Reality, Internet of Things and Wearables.

The PayPal Developer team closely follow all new and emerging technologies and as such has submitted a some proposed topics that we would love to present at the next conference.

But we need your help

To aid us in our quest to present these ideas of industry at SXSW 2015 we need you to vote up our topics…

For the Love of Pets and Technology!

Calling all Animal lovers! In this modern world, isn’t it cool that we can communicate, interact, observe and play with our pets in so many different ways using new technology?

Death to passwords – mobile security done right

User authentication in mobile applications is a very common and integral use case. Implementing regular passwords is an easy solution for developers but comes with several pitfalls that impair user experience like (re-)entering passwords, the need to create a new unique password or even just the input of personal data on a flaky keyboard while registering a new account.

Identity in the Future of Embeddables & Wearables

Stemming from the rapid prototyping maker movement, technology has taken a huge leap forward to begin true integrations with the human body. As the human body becomes a natural extension of technology itself, ways of identifying a person to the technology around them is shifting from antiquated external body definitions, to internal body functions.

IoT Hivebots

low powered IoT robotics is not a new concept and for most home or office configurations connecting multiple devices to a central controlling processor is not uncommon but when the central controller is incapacitated the result is passed on to the attached devices.

The DNA of FinTech APIs

APIs are changing the nature of businesses – telephony, computing, and credit card processing come to mind immediately. Financial services pose special risks and opportunities for API makers and consumers.

Future of Bitcoin Serving the Unbanked

Crypto currency, in particular Bitcoin, is transforming financial services. What does the future hold for the next couple of years? The number of bitcoin and virtual currency startups on Angel List has nearly doubled in the last six months to ~500.

Demystifying Payment Tech for Startups

Startups increasingly have more and more difficulties figuring out the best way to collect payments as they begin to monetize their businesses. The setup process is not very transparent, nor are the fees, risks and perisls of selecting the wrong mechanism for accepting payments.

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.

New Year. New Family.

By

2013 was a busy year for the PayPal Developer Relations team. We kicked off our first-ever global hackathon competition, Battle Hack, and we created the first startup program at PayPal — Start-up Blueprint — to help developers succeed and grow. But, what we were most excited about was that we welcomed Braintree into the PayPal family last year.

As we start off the New Year, we’re excited to share that the PayPal Developer Relations team is joining the Braintree team. Braintree has specialised in working with the top start-ups and developers like Uber, Fab and Airbnb for many years and so moving our Developer Relations team into Braintree makes sense as we will be closer to our customers — the awesome developers and start-ups!

Just because we’re moving over to Braintree doesn’t mean anything changes for PayPal developers. Our team will continue sharing information and best practices for PayPal APIs, but now we’ll be able to do the same for Braintree SDKs. By having knowledge of both sets of tools, we will be able to better help developers find the best payment solution for their needs.

We look forward to what 2014 brings. We’ll continue bringing our Battle Hack competition to more cities around the world, and signing up more start-ups and incubators for our Blueprint Startup program. Feel free to reach out to us @PayPalDev or email us if you have any questions!

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.