Frustrated by PayPal's all-over-the-map API documentation? Can't find the answers on the interwebz? Not to worry! Getting to the root of why your API calls aren't working isn't as difficult as you might think.

The Tool for the Job

First you'll want to go and get the Advanced REST Client for Chrome. This extension allows you to create and send any kind of HTTP request with any Headers, URI, or Query String. You can even send File Uploads. The response for each of your requests will be parsed and displayed below the form.

Minor Rant

I use this extension quite a bit, but I'll give you one specific example where it really helps: PayPal. If you've ever had to integrate PayPal into a web site's shopping cart (or similar) system, you are all too familiar with the frustration of working with a poorly documented API. Not that there isn't enough documentation for PayPal's API. There is probably too much; quite a bit of which is inaccurate or, at the very least, ambiguous. Anyways.. I think the point I am trying to make is that it can be quite useful if we can easily and quickly debug API related issues; hence, the REST Client.

Down to Bidness

With PayPal's Web Payments Standard API, there are two key types of messages your web site will have to be able to receive and process:

Payment Data Transfers (PDT) happen when a customer is redirected back to your web site immediately after making their payment at PayPal. This one is pretty simple to debug, even with just your browser. It's a simple HTTP GET request that your customer's browser makes when they navigate back to your web site. The variables are all plainly visible in the URL.

Instant Payment Notifications (IPN) are a bit less clear. After a customer makes a payment to your PayPal account, PayPal will send an HTTP POST request to your server (at the URL you set in your PayPal account). This is where the REST Client will shine.

Fire up the Advanced REST Client extension. In the URL field at the top of the form, put your site's IPN URL. Change the Method to POST. Skip the Headers, we won't need that for this example. For the Body field, we're going to use the Raw Input text area.

Log in to your PayPal Merchant Account. If you're still in the sandbox environment, log in to that and then log in to your test merchant account. Go to your account's IPN History page. If you have any failed IPN messages associated with this account, they will be displayed on this page. View the message body of one of the more recent failed IPN attempts. Copy the entire message body and, back in your REST Client, paste it into the Body Raw Input field. Now send the request. You should now see what PayPal's servers see when they attempt to communicate with your web site.

Wrap Up

Of course the REST Client can, and should, be used for more than just debugging PayPal integrations. Personally, I use it whenever I have inter-application communications going on so that I can clearly see all the inputs and outputs of my applications' HTTP requests and responses.