Tag Archives: programming

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

By

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.

Announcing the new RESTful API Node.js SDK

By

Since the launch of the new PayPal RESTful APIs, the development teams have been hard at work to provide the development community with new features and ways of working with our new initiatives.

With that said, I am happy to announce the launch of the new Node.js SDK for the RESTful APIs. As a Node.js developer myself, I am always happy to see how much eBay and PayPal support the Node.js community.

Getting the SDK As with all of our SDKs, the Node.js SDK is available on the

PayPal Github account. What makes this approach excellent for the community is that all issues and enhancements that users may want to contribute can be done directly through the Github project itself, meaning that the progress and work that the teams are doing to enhance the projects are completely transparent.

To find samples for working with the SDK, you can also take a look through the Node.js SDK sample repository. This is an excellent place to get started.

Using the SDK There are a few steps that we need to go through in order to integrate the SDK into a Node.js application.

1. Create the package.json file To start out an integration, we first need to create our package.json file that will give our application all of its configuration information.

The easiest way to get started is to copy the sample package.json file from the PayPal Node.js SDK Github repository. Once copied to your application folder, open it up for editing.

We now need to add the PayPal Node.js SDK as a dependency for our application. Go down to the dependencies object declaration and add a new paypal-rest-sdk definition. That section should now look like the following: "dependencies": {
"node-uuid": "*",
"paypal-rest-sdk": "*"
}
2. Install dependencies and create your test file With the package.json file created, we now need to use it to install our application dependencies. At the application folder root, where the package.json file is, simply run the following command: npm install Once completed, you should now see a new node_modules folder within your project, containing all of the required project dependencies. Next, go ahead and create a new Node.js application file, such as test.js, where we will put all of our test code. 3. Configure your application details Open up your new Node.js file to begin adding in our application configuration details. We’re going to start by creating a new variable for the SDK, paypal_sdk. With that in place, we then create a PayPal configuration object. This section will contain:
* host: The API host to use, api.sandbox.paypal.com for the PayPal sandbox, or api.paypal.com for live requests.
* port: The port to use.
* client_id: Your PayPal application client id.
* client_secret: Your PayPal application client secret.

4. Making your first request Now that the configuration object is in place, we can make our first request. Let’s go ahead and store credit card information in the vault. We start by creating a credit card object with the information that we want to store in the vault. Once that’s in place, we make a call to the credit_card.create method to initiate the storage request. Once the code is called, you should see a valid response coming back with the credit card store response, looking something like this:

Going Further To continue exploring the Node.js SDK and the methods available, you can take a look through the

SDK lib itself at the end of the file in the return structure, or see the API methods on the PayPal Developer site.

If you want to see what other SDKs are available, you can explore this earlier SDK announcement post.

Authenticating with OAuth 2 in the new RESTful APIs

By

With the launch of the new PayPal REST APIs there comes a new way of authenticating your application to begin receiving payments, issuing refunds, storing credit card information and a slew of other features.

In this post, I’m going to introduce you to working with the OAuth 2 bearer tokens that the REST APIs use as their auth mechanism. At the end of the post, you should have a good understanding on how the system works and how to use it to build out calls to the new APIs.

A little background on our use of OAuth 2

Before we get into the code, there are a few things that you should know about the PayPal implementation of OAuth 2 that you may or may not be familiar with.

You may already be used to working with a flow where the user will have to grant your application permission to use their information or do something on their behalf using a regular access token. Instead of this flow, PayPal uses bearer tokens that do not have a user step to sign in and authorize the application in this familiar construct. Instead, the bearer token is obtained by passing your client id and secret keys using basic auth to PayPal servers. Once the bearer token is obtained, it will be supplied as an authorization header when making GET / POST requests to work with the APIs.

You can find more information on our implementation here.

Defining your keys and URIs

The first step that you’re going to need to do is to define your application keys and the URIs that we’re going to be working with.


First off, go to the REST API Credentials page directly (or from developer.paypal.com go to the “Applications” tab, then click on “REST API credentials” from the left hand menu). On this page you will be able to see your sandbox and live credentials. Simply copy the values that you want to use into the code sample above. The URI endpoints for sandbox and live are already defined.

Fetching the bearer token

Now that we have our URIs and keys defined, we can start creating a class wrapper with a few methods to fetch the OAuth 2 bearer token. Within this class, we will have several main pieces that we will begin working with:

  • Properties: We define two private properties for the call to store the access token / bearer token and the token type (which will be Bearer).
  • Constructor method: Our constructor will make the requests to PayPal servers (via the cURL method) to obtain the bearer token and store it in the properties above.
  • cURL method: This will not only be the method that makes the HTTP requests to obtain the bearer token, but will also handle any HTTP requests to invoke PayPal APIs using the bearer token.

If we break down these code sample pieces into their individual methods, we can see the flow of how they work.

Constructor
When a new instance of the paypal class in instantiated, the constructor will be invoked. In the code, it goes through several steps: 1. We set up the POST parameter, grant type, with a value of client_credentials to instruct the OAuth 2 request to PayPal that we are making a request for client credentials. 2. We then set up the URI that we will make this HTTP POST request to, which will be https://api.sandbox.paypal.com/v1/oauth2/token on the sandbox. 3. Next we issue an HTTP POST request through the cURL method to return our bearer token. An object containing these details will be returned to us. 4. We then parse apart that object to store the bearer token and token type in our private properties.

cURL
The cURL method is going to allow us to generate requests for our bearer tokens, but also permit authenticated HTTP GET and POST requests to the APIs once we have that token. The method has a few parameters that can be supplied: * url: the URL that we will make a request to. * method: The HTTP request method to be used, either GET or POST in our cases. * postvals: The POST body to be supplied with a POST request. * auth: A boolean value for whether we are making a request to get the bearer token. If true, the basic auth headers with our key / secret will be used instead of the bearer token authorization header.

We first initialize the cURL request with curl_init. Next we need to set the headers of the request. If we are making a request to get the bearer token ($auth == true), then we set up a basic auth header, passing in our client id and secret as the username and password values. If we are making a request to the APIs using the bearer token ($auth == false), then we set a content type header and an Authorization header, supplying the token type and the bearer token.

We then set up the cURL options that we want to use, which are fairly standard. We set up options to send a header, enable verbose output, return the response from the server, and set a 10 second timeout on the request (because the bearer token fetch may take ~ 5 seconds on sandbox to respond. If an HTTP POST request is being made, we also set options for the HTTP request type and supply the POST body to the request.

Lastly, we make the cURL request, then split the response into the header and body and return both pieces.

Making a call with the bearer token

At this point we have everything we need to start making requests to the APIs using the cURL method. Let’s take a look at what one of these requests will look like if we want to process a credit card payment from someone.


In this simple wrapper, the user will supply a JSON string for the payment POST request that they want to make, based on the API specification for the request. We simply need to create a POST body object, set the URI (which will be https://api.sandbox.paypal.com/v1/payments/payment on the sandbox), then return the response from the cURL request. What we should be left with is an object containing the success response, or an appropriate error if something went wrong.

That’s really all you need to do to work with the new REST APIs using bearer tokens. There are also SDKs available if you want to bypass this deep integration, which are detailed (with samples) in this post.

Tell me what might be helpful for you

In my next post on the subject I will post out a new PHP API wrapper that extends everything we went through here, and includes methods for working with all functionality of the new APIs, and includes proper error handling. Of course, I really do want to hear from everyone to let me know if there are any samples or walkthroughs in particular that you might find helpful. Would you like to see some video screencast, other tutorials, other languages? Please let me know and I’ll do what I can to put together that for you.

The New PayPal Developer APIs

By

ava_jonAs requested from our community, today we’re launching a whole new way for you to work with PayPal. To keep in line with the way that people work with the web today, this launch will include a new series of RESTful APIs all launched under a new developer portal, which is complete with streamlined docs and services. What you’ll notice the most from these new APIs is that you will no longer be picking a different API depending on an intricacy of what you need payments for. Now you’ll instead start including elements a la carte from a single source. If you need to make a payment, you call one endpoint, if you need to issue a refund you hit another endpoint. We wanted to make the experience as seamless as possible for our users.

What can I do with the new APIs?

Within this first release of our new systems, there are a few methods for you to begin working with. These include:

  • Payments: Allows you to make payments or get information about a payment.
  • Sales: Allows you to fetch and refund payments that have been completed (sales transactions).
  • Refunds: Allows you to get information about refunds that were made through the sales endpoints.
  • Vault: Allows you to store and look up credit cards securely. These new APIs will use

OAuth2 as the authentication mechanism for making your requests. If you haven’t used it before, it is a simple and secure token based system for securing and authenticating your applications. In the coming months, you’ll see enhancements to this product set coming through.

Are there any samples or SDKs available?

Where would a new set of APIs be without some appropriate samples and SDKs to speed things along. While we have a lot of products currently in development, here is what we have in this first release: PHP:

SDK | Samples Java: SDK | Samples C#: SDK | Samples Ruby: SDK | Samples cURL: Samples

Where can I make feature requests, file issues or get help?

At the same time that we are launching this new suite of APIs, we want to make sure that the development community can be as involved as they would like to be in the features and enhancements of these products. Should you have any feature requests for our APIs, have a great sample that you want to share back that have helped you, or are encountering any issues with the SDKs or samples, we would love for you to file those requests on the Github sample code or SDK projects that they relate to. If you have questions about using the products, or want some help with the integrations, our teams will be working on StackOverflow to help with those questions. Simply

reach out to us on there and tag your post with PayPal to ensure that we see it, and we’ll make sure to reach out and help.

Will I still be able to use all of my old code and integrations?

We wouldn’t be PayPal if we broke your development experiences with a new product release. We will still be supporting all of our existing

Classic APIs, so existing developers will not be impacted in the slightest.

The future of these products

As we go further into 2013 and beyond, you will see constant enhancements to our new RESTful suite of APIs. We will support existing product sets that you have come to know and love, and include some amazing new product lines for you to enable commerce in incredibly easy and dynamic ways.