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

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:

• Setting up an app and making your first call
• What’s available in the new developer APIs

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.