Monthly Archives: May 2013

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.

A small thought on Objective-C categories

By

I recently hit what seems to me a cute little example of how Objective-C Categories might be used. If you are unfamiliar with them, the Apple docs are good. They are often used to extend pre-existing classes from Apple i.e. where you don’t have the source code.

I had what could be termed a Domain Model in an iOS project. It did not know anything about the user interface, naturally. There came a point where the Model was to be connected into the UI. The UI was already written to use a C-style enumeration of Model types (when the UIPickerView presented different values to choose from, and the UI code handled the user’s pick).

The Model had no internal need for a categorized, constrained list of the domain types. If you have seen things like the expression problem or a visitor design, you will probably have thought about where to put code. It is not always an easy thing to decide. In my case, the Model was a fine fit for regular OO where you can add new types implementing a standard set of methods, rather than something ‘procedural’ or ‘functional’ where you have a fixed set of types and are more interested in adding new methods for all of them.

Anyway, I simply added an enumeration directly in the Model layer. Each Model class exposed a read-only property of that enumeration type. Problem solved; the UI could get on with life. There are times when you cannot or don’t want to boil the ocean.

But if one had a strong urge to avoid putting UI knowledge inside the base level of the Domain, how to do it? Something that came to mind was to use Categories: extend the Domain classes with the enum property for UI consumption, leaving the base Domain classes alone. Given how the project was already going, the overhead would be an extra pair of files (one .h, one .m) per Domain class, of which there are only 3 since it is a small R&D project. Each of those files would be pretty succinct. Additionally, the UI files would change their imports from e.g. “DomainModelClassX.h” to “DomainModelClassX+TypeEnumeration.h”.

The advantage is that the base Domain code still doesn’t know anything about this enumeration, while the UI gets what it wants. Disadvantages include there being more files in the project (not an inherent evil, but something to be wary of); that the UI code needs to know the right files to import; and that concerns are split across several files (future developers might find this design obscure vs. the enum-in-Model approach). When I consider that the Categories could pull out further UI-Model specific code like display strings for the various Model types, I’m even more attracted to the Category approach. It seems like a pretty nice way to make the two layers meet.

There are of course other ways to wrestle with all this in Objective-C, let alone other languages. Scala, Perl, and PHP support traits. C# supports extension methods. Lisps support multimethods. (You could probably even perversely use an Aspect Oriented Programming library to address the issues.) Some of those languages also offer stronger static typing than Objective-C in this arena, if that floats your particular boat.

Interactive elements within a grid layout

By

Often times, the best way to begin marking up HTML content is to put aside the visual design and concentrate on the semantics. A good example of this is when a design first appears to be a data table but actually includes content other than data.

The Challenge

In the following wireframe design, transaction records are displayed in a table-like format, a grid. Each row is designed to be a link (the entire row) and has a grey hover/focus effect. Data includes a date, description, and dollar amount. There is also a menu button in each of the records; clicking it opens a drop down menu.

Screenshot of layout grid

At first glance, the design appears to be a data table. But the row link and the menu button within a data table create fundamental markup and accessibility issues. (If the design called for traditional text links instead of the row link and menu button, a data table is a solid option.) A layout table would create similar issues as a data table but we’re not going to go there in the name of Web Standards.

First Approaches

Definition List

One idea for marking up this content is to use a description list. For each row, a unique identifier (like a record number) would be the DT and would be visually hidden. The rest of the row content would be contained in DD elements. Example:

<dl>
  <dt>Record 1</dt>
  <dd>date</dd>
  <dd>description</dd>
  <dd>amount</dd>
  <dd>[menu button]</dd>
</dl>

But like the table, the row link would certainly be challenging, and would add to the complexity of the extensive CSS already required to make this fit the visual design. Also, the menu button doesn’t fit the semantic meaning of a DD (description data).

ARIA Grid

Another approach is to use divs and spans with the ARIA grid role along with the associated row and gridcell roles. In this technique, “the grid construct describes relationships between data such that it may be used for different presentations”. In other words, a more flexible data table-like structure can be developed. Example:

<div role="grid">
  <div role="row">
    <a href="#">
      <span role="gridcell" class="date">date</span>
      <span role="gridcell" class="desc">description</span>
      <span role="gridcell" class="price">amount</span>
    </a>
    <span role="gridcell" class="menu">[menu button]</span>
  </div>
</div>

To give context to screen reader users, it may be a good idea to add the aria-labelledby property and the rowheader and columnheader roles.

The main problem with this technique is support. ARIA is still relatively new, and inconsistent results are found among the different screen readers (JAWS, NVDA, VoiceOver). There is also a lack of semantic elements, and the abundance of ARIA creates code complexity (especially to those not yet familiar with ARIA).

A Solution

Let’s take a step back and simplify. There are three main piece to the puzzle: a unique identifier (not in visual design), some linked text, and a menu button.

One feasible solution is to use:

  • a heading as the unique identifier for each record (like the DT in the example above), 
  • an anchor element containing spans for the link (like the ARIA example above), 
  • a div to contain the menu button.

Divs are also used for CSS hooks in order to create the grid/table-like design. Example:

<div class="table">
  <div class="tableRow">
    <h3>Record 1</h3>
    <div class="tableRowInner">
      <a href="foo.html">
        <span class="tableColumn date">date</span>
        <span class="tableColumn desc">description</span>
        <span class="tableColumn price">amount</span>
      </a>
    </div>
    <div>[menu button]</div>
  </div>
</div>

For the title of the grid content, let’s use a heading, say an H2 in this case. For proper heading levels, each record will then require an H3 heading. This is great for not only page structure but also helps screen readers users for context and navigation. The menu button is separated in its own Div but still falls under the record’s H3 heading.

Using CSS we create the grid design. Here’s an excerpt:

.tableRow .tableColumn {
  display: block;
  float: left;
  color: #333;
}
.tableRow .tableRowInner > a {
  display: block;
  float: left;
  padding: .75rem 0;
  text-decoration: none;
  width: 118%;
}
.tableRowInner {
  float: left;
  width: 85%;
}
.tableRow:last-child .tableRowInner {
  padding-bottom: 1.5em;
}
.tableRow .tableColumn.date {
  width: 25%;
}
.tableRow .tableColumn.desc {
  width: 40%;
}
.tableRow .tableColumn.price {
  text-align: right;
  width: 25%;
}

With some CSS magic, we can position the menu button to appear within the row (check the widths of the row and anchor). And there we have it; a grid layout with interactive elements which is accessible. It also a robust solution; it functions well without JavaScript or without CSS.

Check out the working example

Final Words

Developing ideal solutions can be difficult in these days of complex web apps, stringent design requirements, and increasing accessibility concerns. The solution in this article isn’t perfect (could use less divs and spans and more semantic elements), but it certainly does the job. Do you have any suggestions for this issue?