Monthly Archives: July 2014

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.

Subscriptions are Now Available in the PayPal REST APIs

By

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.