News Archive
PhpRiot Newsletter
Your Email Address:

More information

Breaking down the PayPal API

Note: This article was originally published at Planet PHP on 20 April 1380.
Planet PHP

PayPal is the most popular platform for receiving online payments. The relative ease of opening a PayPal account and receiving payments compared to opening a merchant account for a traditional payment gateway is the number one reason, and another is the comprehensive API they provide for their payment services.

Foreclosure: The PayPal API is amongst the worst I've ever had to deal with - inconsistencies, sometimes poor and conflicting documentation, unpredictable failures and account changes and major differences between the live and sandbox versions all conspire to make working with the PayPal API quite a pain in the ass.

Unfortunately, there doesn't seem to be any better alternatives currently, so hopefully this guide will help ease the pain for some of you out there taking your lumps working the API into your applications.

The different payment options

PayPal offers a variety of payment options, which might be confusing at first:

  • Express Checkout - The premier PayPal service. Express checkout allows you to receive payments without having a merchant account or meeting special requirements other than having your account verified (either via a bank account or a credit card).Previously you could receive Express Checkout payments from PayPal users only, but PayPal has since added a credit-card option for non-PayPal users making this service accessible to practically anyone with a major credit-card.Note that the Express Checkout process occurs on the PayPal platform and thus can never be fully integrated into your site experience completely.
  • Direct Payment - The Direct Payment method allows you to receive credit-card payments directly through an API call. This allows you to host the payment process on your site in full, which might make for a more complete shopping experience for shoppers.The Direct Payment method has several variations that allow you to authorize a payment and complete it at a later date - the appropriately named methods Authorization and Capture. The direct payments methods are a part of the Website Payments Pro API, which is only available U.S accounts.
  • Recurring Payments - allow you to set up a recurring transaction - i.e, a subscription payment.
  • Mass Payments - allow you to transfer money to multiple accounts at once.

This is a comprehensive list, but it covers the main payment options (see the docs for more).

Making API requests

PayPal supports two main formats over HTTP - NVP and SOAP. NVP is short for Node-Value-Pairs and SOAP stands for Simple Object Access Protocol. I will cover the NVP approach which I prefer to SOAP's comparatively verbose and general complex syntax.

Each of the API methods have different parameters but they all share some basic parameters which are used to identify the API account and sign the transaction. Those include:

  • USER - Your PayPal API Username.
  • PWD - Your PayPal API Password.
  • VERSION - Version number of the NVP API service, such as 56.0.
  • SIGNATURE - Your PayPal API signature string. This parameter is optional if you use a certificate to authenticate

The last required parameter is METHOD which declares which API method we are calling.

Requests are made over HTTPS. We'll use cURL to build up our basic request, and encapsulate the process in a function:

function paypalApiRequest($method,$params = array()) { if(empty($method)) { //Check if API method is not empty return "/

Truncated by Planet PHP, read more at the original (another 17669 bytes)