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
- Authenticating an app with OAuth 2
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:
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:
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:
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.
- New REST API Feature: Setting a Receiver for Payments
- PayPal is Now Available Through WooCommerce 2.6 Onboarding Wizard
- Adaptive Payments is Moving to Limited Release – What you Need to Know
- Building the Next Step in Payment Tutorials with Stack Overflow Docs
Connect with us!
- January 2017
- December 2016
- October 2016
- September 2016
- July 2016
- May 2016
- March 2016
- November 2015
- September 2015
- August 2015
- June 2015
- April 2015
- March 2015
- November 2014
- October 2014
- August 2014
- July 2014
- March 2014
- February 2014
- January 2014
- December 2013
- October 2013
- September 2013
- August 2013
- July 2013
- June 2013
- May 2013
- April 2013
- March 2013