Getting Started With the PayPal API - Smashing Coding

Getting Started With The PayPal APIURL: http://coding.smashingmagazine.com/2011/09/05/getting-started-with-the-paypal-api/

PayPal is the most popular platform for receiving online payments today. The ease of openinga PayPal account and receiving payments compared to opening a merchant account with atraditional payment gateway is probably the number one reason for its popularity, with a closesecond being the comprehensive API that PayPal provides for its payment services. In thispost, I will break down some of the techniques and approaches to working with thePayPal API, in order to make integration and troubleshooting simpler and easier.

Disclaimer: PayPal’s API is among the worst I’ve ever had to deal with. Inconsistencies,sometimes poor or conflicting documentation, unpredictable failures and account changes,and major differences between the live and sandbox versions all conspire to make the PayPalAPI quite a pain in the arse to work with. Over the years, I’ve taken my lumps from workingquite a bit with the PayPal API, and I’ve published the results of my hard-learned lessons as acommercial PHP PayPal API component on the source-code marketplace Binpress.

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 and without having to meet special requirements other than

verifying your account (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

PayPal’s platform and thus can never be fully integrated in your website’s experience.

Direct Payment

The Direct Payment method allows you to receive credit-card payments directly through

Getting Started With The PayPal API - Smashing Coding http://coding.smashingmagazine.com/2011/09/05/getting-started-with-th...

1 sur 17 05/10/2011 18:33

an API call. This enables you to host the payment process on your website in full, which

might make for a more complete shopping experience for your customers. The Direct

Payment method has several variations that enable you to authorize a payment and

complete it at a later date: the appropriately named Authorization and Capture

methods. These variations are a part of the Website Payments Pro API, which is

available only to US, Canadian and UK accounts.

Recurring Payments

This allows you to set up a recurring transaction (i.e. a subscription payment).

Mass Payments

This allows you to transfer money to multiple accounts at once.

Adaptive Payments

Here is another API for sending funds to multiple recipients, with some differences from

the Mass Payments API. (Did I mention that the PayPal API is confusing and a bit

redundant?)

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

Making API Requests

PayPal supports two main formats over HTTP: NVP and SOAP. NVP is short for Name-ValuePair, and SOAP stands for Simple Object Access Protocol. I will cover the NVP approach,which I prefer to SOAP’s relatively verbose and complex syntax.

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

USER

Your PayPal API user name.

PWD

Your PayPal API password.

VERSION

The version number of the NVP API service, such as 74.0 (the most recent as of this

writing).

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 our basic request, and thenencapsulate the process in a class:


2 sur 17 05/10/2011 18:33

01 class Paypal {

02 /**

03 * Last error message(s)

04 * @var array

05 */

06 protected $_errors = array();

07

08 /**

09 * API Credentials

10 * Use the correct credentials for the environment in use (Live /

Sandbox)

11 * @var array

12 */

13 protected $_credentials = array(

14 'USER' => 'seller_1297608781_biz_api1.lionite.com',

15 'PWD' => '1297608792',

16 'SIGNATURE' =>

'A3g66.FS3NAf4mkHn3BDQdpo6JD.ACcPc4wMrInvUEqO3Uapovity47p',

17 );

18

19 /**

20 * API endpoint

21 * Live - https://api-3t.paypal.com/nvp

22 * Sandbox - https://api-3t.sandbox.paypal.com/nvp

23 * @var string

24 */

25 protected $_endPoint = 'https://api-3t.sandbox.paypal.com/nvp';

26

27 /**

28 * API Version

29 * @var string

30 */

31 protected $_version = '74.0';


3 sur 17 05/10/2011 18:33

32

33 /**

34 * Make API request

35 *

36 * @param string $method string API method to request

37 * @param array $params Additional request parameters

38 * @return array / boolean Response array / boolean false on

failure

39 */

40 public function request($method,$params = array()) {

41 $this -> _errors = array();

42 if( empty($method) ) { //Check if API method is not empty

43 $this -> _errors = array('API method is missing');

44 return false;

45 }

46

47 //Our request parameters

48 $requestParams = array(

49 'METHOD' => $method,

50 'VERSION' => $this -> _version

51 ) + $this -> _credentials;

52

53 //Building our NVP string

54 $request = http_build_query($requestParams + $params);

55

56 //cURL settings

57 $curlOptions = array (

58 CURLOPT_URL => $this -> _endPoint,

59 CURLOPT_VERBOSE => 1,

60 CURLOPT_SSL_VERIFYPEER => true,

61 CURLOPT_SSL_VERIFYHOST => 2,

62 CURLOPT_CAINFO => dirname(__FILE__) . '/cacert.pem', //CA

cert file


4 sur 17 05/10/2011 18:33

63 CURLOPT_RETURNTRANSFER => 1,

64 CURLOPT_POST => 1,

65 CURLOPT_POSTFIELDS => $request

66 );

67

68 $ch = curl_init();

69 curl_setopt_array($ch,$curlOptions);

70

71 //Sending our request - $response will hold the API response

72 $response = curl_exec($ch);

73

74 //Checking for cURL errors

75 if (curl_errno($ch)) {

76 $this -> _errors = curl_error($ch);

77 curl_close($ch);

78 return false;

79 //Handle errors

80 } else {

81 curl_close($ch);

82 $responseArray = array();

83 parse_str($response,$responseArray); // Break the NVP

string to an array

84 return $responseArray;

85 }

86 }

87 }

Note that I use a CA certificate file for SSL certificate validation. You can obtain the file fromthe cURL website or any trusted source. Update the path to the certificate file according towhere you’ve placed it.

The response returned will be in NVP format as well, and I reformat it into an array beforereturning it. A parameter named ACK signifies the status of the request: Success or

SuccessWithWarning when the request succeeds, and Error or Warning when the request

fails.


5 sur 17 05/10/2011 18:33

A request could fail for many reasons, and there are different reasons for each API method,which are covered in detail in the manual. We’ll go over some further down in this article andlook at ways to handle them. Keep in mind that the parameter values are case-sensitive, socode against them accordingly.

Express Checkout

One of the most popular APIs is the Express Checkout API, which enables you to receivepayments without opening a Website Payments Pro account (which is available only toverified US accounts) or hosting the actual transaction yourself (which requires additionalsecurity).

The Express Checkout process works as follows:

We request a checkout token from PayPal using the transaction details;1.

If successful, we redirect the user to the PayPal endpoint using the received token;2.

The user completes or cancels the payment on the PayPal platform and is redirected

back to our website;

3.

We complete the payment either when the user is redirected back or via an Instant

Payment Notification (IPN).

4.

1. Getting the Checkout Token:SetExpressCheckout

We initiate the Express Checkout process by passing the order details to the PayPal API, andwe receive a token string that identifies it. This token would be used in the next step toredirect to PayPal.

Here are the required parameters:


6 sur 17 05/10/2011 18:33

METHOD

This is the API method that we’re using (i.e. SetExpressCheckout).

RETURNURL

The URL that the user will be redirected to after the payment process is completed.

CANCELURL

The URL that the user will be redirected to after having cancelled the payment process.

PAYMENTREQUEST_0_AMT

The transaction’s total amount. This must have two decimal places, with the decimal

separator being a period (.). The optional thousands separator must be a comma (,).

PAYMENTREQUEST_0_ITEMAMT

The total cost of the items in the order, excluding shipping, taxes and other costs. If

there are no extra costs, then it should be the same value as PAYMENTREQUEST_0_AMT.

We can pass additional parameters to add more information about the order, some of whichhave default values:

PAYMENTREQUEST_0_CURRENCYCODE

The payment’s currency, as a three-letter code. The default is USD.

PAYMENTREQUEST_0_SHIPPINGAMT

The total shipping costs for this order.

PAYMENTREQUEST_0_TAXAMT

The total tax amount for this order. This is required if per-item tax is specified (see

below).

PAYMENTREQUEST_0_DESC

The order’s description.

We can also add details about individual items in the order:

L_PAYMENTREQUEST_0_NAMEm

The item’s name.

L_PAYMENTREQUEST_0_DESCm

The item’s description.

L_PAYMENTREQUEST_0_AMTm

The item’s cost.

L_PAYMENTREQUEST_0_QTYm

The quantity of an item.

The variable index m identifies the item. (Use the same variable for all details of the same

item.)

There are many other optional parameters, which can be found in the API documentation.

We’ll use the function that we wrote above to build the SetExpressCheckout request:


7 sur 17 05/10/2011 18:33

01 //Our request parameters


03 'RETURNURL' => 'http://www.yourdomain.com/payment/success',

04 'CANCELURL' => 'http://www.yourdomain.com/payment/cancelled'

05 );

06

07 $orderParams = array(

08 'PAYMENTREQUEST_0_AMT' => '500',

09 'PAYMENTREQUEST_0_SHIPPINGAMT' => '4',

10 'PAYMENTREQUEST_0_CURRENCYCODE' => 'GBP',

11 'PAYMENTREQUEST_0_ITEMAMT' => '496'

12 );

13

14 $item = array(

15 'L_PAYMENTREQUEST_0_NAME0' => 'iPhone',

16 'L_PAYMENTREQUEST_0_DESC0' => 'White iPhone, 16GB',

17 'L_PAYMENTREQUEST_0_AMT0' => '496',

18 'L_PAYMENTREQUEST_0_QTY0' => '1'

19 );

20

21 $paypal = new Paypal();

22$response = $paypal -> request('SetExpressCheckout',$requestParams +

$orderParams + $item);

2. Redirecting to PayPal Using the CheckoutExpress Token

If the request is successful, we’ll receive a checkout token in the TOKEN parameter of the

response.

1if(is_array($response) && $response['ACK'] == 'Success') { //Request

successful

2 $token = $response['TOKEN'];

3 header( 'Location: https://www.paypal.com/webscr?cmd=_express-


8 sur 17 05/10/2011 18:33

checkout&token=' . urlencode($token) );

4 }

The user now goes through the purchase process on PayPal’s website. When they confirm orcancel it, they will return to one of the URLs that we’ve specified in the request.

3. Completing the Transaction

Assuming the user confirms the transaction, they will be redirected to our website by PayPal.At this point, we should use two relevant API methods: DoExpressCheckoutPayment will

complete the transaction, but before that we might want to get additional information on thebuyer using GetExpressCheckoutDetails.

PayPal will redirect the user back from the purchase with the checkout token, which we willuse to call those methods. The token will be available in the URL query parameters via thetoken parameter. We will check for its existence in the confirmation URL and then send our

API requests if we find it.

The GetExpressCheckoutDetails method requires only the checkout token.

DoExpressCheckoutPayment requires a couple of additional parameters:

PAYMENTREQUEST_0_PAYMENTACTION

This is the payment action. It should be set to Sale unless we’ve specified a different

action in the SetExpressCheckout method (possible values include Authorization

and Capture).

PAYERID

This is the unique identification for the PayPal account. This, too, is returned in the URL

query parameters (in the PayerID parameter) and can also be retrieved from the details

returned by GetExpressCheckoutDetails.

01if( isset($_GET['token']) && !empty($_GET['token']) ) { // Token

parameter exists

02 // Get checkout details, including buyer information.

03 // We can save it for future reference or cross-check with the

data we have


05 $checkoutDetails = $paypal -> request('GetExpressCheckoutDetails',

array('TOKEN' => $_GET['token']));

06

07 // Complete the checkout transaction


9 sur 17 05/10/2011 18:33


09 'TOKEN' => $_GET['token'],

10 'PAYMENTACTION' => 'Sale',

11 'PAYERID' => $_GET['PayerID'],

12 'PAYMENTREQUEST_0_AMT' => '500', // Same amount as in the

original request

13 'PAYMENTREQUEST_0_CURRENCYCODE' => 'GBP' // Same currency as

the original request

14 );

15

16 $response = $paypal ->

request('DoExpressCheckoutPayment',$requestParams);

17 if( is_array($response) && $response['ACK'] == 'Success') { //

Payment successful

18 // We'll fetch the transaction ID for internal bookkeeping

19 $transactionId = $response['PAYMENTINFO_0_TRANSACTIONID'];

20 }

21 }

Direct Payment

The Direct Payment API allows you to receive payments directly on your website orapplication, giving you complete control over the checkout process. PayPal tends to pushusers to register and use a PayPal account, which is understandable, but this conflictssomewhat with our interest to make the payment process as simple and clear as possible forour customers. For this reason, full control over the checkout process is preferred and gives usmore options to optimize sales and generate more sales.

The process is a bit simpler than that of Express Checkout, because the entire interaction


10 sur 17 05/10/2011 18:33

occurs on our website, and we need to perform just one API call to process a normal payment:DoDirectPayment.

A couple of more API requests are required if you want to perform a transaction that is billedat a later date (for example, when you ship the product or confirm availability). These wouldbe the Authorization & Capture API methods, which I will not cover in this post, but be awarethat this option exists.

DirectPayment Parameters

DirectPayment requires different parameters than Express Checkout, as to be expected. Whilethe transaction details parameters are similar (with different key names, to make it moreinteresting), the method also requires credit-card and address information.

DirectPayment’s basic parameters:

METHOD

This is DoDirectPayment.

IPADDRESS

This is the IP address of the payer. In PHP, we can retrieve it using the superglobal

$_SERVER['REMOTE_ADDR']. You’ll have to do a bit more work to get the IP when

dealing with set-ups that have a proxy between the PHP process and the outside

network (such as nginx).

PAYMENTACTION

This is the type of action that we want to perform. A value of Sale indicates an

immediate transaction. A value of Authorization indicates that this transaction will

not be performed immediately, but rather will be captured later using the Authorization

& Capture API mentioned earlier.

Credit-card details:

CREDITCARDTYPE

The credit-card type (Visa, MasterCard, etc.). See the API documentation for the full list.

ACCT

The credit-card number. (Don’t you love these abbreviated key names?) This must

conform to the particular format of the card’s type.

EXPDATE

The expiration date, in MMYYYY format (i.e. a two-digit month and a four-digit year, as

one string).

CVV2

The “card verification value,” or security code, as it’s sometimes known.

Payer information and address parameters:


11 sur 17 05/10/2011 18:33

FIRSTNAME, LASTNAME

The payer’s first name and last name, respectively (in separate fields). You can also

provide an email address in an EMAIL parameter, but it’s not required.

CITY, STATE, COUNTRYCODE, ZIP

The city, state, country code (as a two-letter code) and zip code parts of the address, all

required.

STREET, STREET2

Two lines for the address (only the first is required).

This address will be used in the address verification system (AVS). You’ll receive a specificerror code if a transaction has failed due to an address verification failure.

The payment details parameters are the same as the ones for Express Checkout, but withslightly different names (AMT, ITEMAMT, CURRENCYCODE, SHIPPINGAMT, TAXAMT and DESC)

and without the PAYMENTREQUEST_0_ prefix. Refer to the previous section or the API

documentation for specific details on those.

Similarly, the item details parameters are similar to those of Express Checkout. These includeL_NAMEm, L_DESCm, L_AMTm and L_QTYm, giving you granular control of item details in the

order summary. The m integer variable is used to account for multiple items (replace with 0, 1and so on for numbered items in the order). See the API documentation for a comprehensivelist of item details.

Performing the Transaction

Sending the request using our function is very similar to GetExpressCheckoutToken. We

pass all of the parameters into the request function as before, with the method set toDoDirectPayment.


02 'IPADDRESS' => $_SERVER['REMOTE_ADDR'],

03 'PAYMENTACTION' => 'Sale'

04 );

05

06 $creditCardDetails = array(

07 'CREDITCARDTYPE' => 'Visa',

08 'ACCT' => '4929802607281663',

09 'EXPDATE' => '062012',

10 'CVV2' => '984'


12 sur 17 05/10/2011 18:33

11 );

12

13 $payerDetails = array(

14 'FIRSTNAME' => 'John',

15 'LASTNAME' => 'Doe',

16 'COUNTRYCODE' => 'US',

17 'STATE' => 'NY',

18 'CITY' => 'New York',

19 'STREET' => '14 Argyle Rd.',

20 'ZIP' => '10010'

21 );

22

23 $orderParams = array(

24 'AMT' => '500',

25 'ITEMAMT' => '496',

26 'SHIPPINGAMT' => '4',

27 'CURRENCYCODE' => 'GBP'

28 );

29

30 $item = array(

31 'L_NAME0' => 'iPhone',

32 'L_DESC0' => 'White iPhone, 16GB',

33 'L_AMT0' => '496',

34 'L_QTY0' => '1'

35 );

36


38 $response = $paypal -> request('DoDirectPayment',

39 $requestParams + $creditCardDetails + $payerDetails + $orderParams

+ $item

40 );

41


13 sur 17 05/10/2011 18:33

42if( is_array($response) && $response['ACK'] == 'Success') { //

Payment successful

43 // We'll fetch the transaction ID for internal bookkeeping

44 $transactionId = $response['TRANSACTIONID'];

45 }

There are plenty of parameters, but all relatively simple.

Error Handling

In a perfect world, this section would not exist. In reality, you will be referring to it quite a lot.PayPal can fail a transaction for a multitude of reasons, not all of which you can control.

The $response variable we returned from our paypalApiRequest() function could

contain a different value than Success for the ACK parameter. That value could be:

Success

Indicates a successful operation.

SuccessWithWarning

Indicates a successful operation, and that messages were returned in the response that

you should examine.

Failure

Indicates a failed operation, and that the response contains one or more error messages

explaining the failure.

FailureWithWarning

Indicates a failed operation, and that messages were returned in the response that you

should examine.

This gives us two success statuses and two failure statuses. The mock code above tests for theSuccess value only, but we could change it to check for SuccessWithWarning as well; and

keep in mind that we need to find out what the warning is. A common scenario is that a DirectPayment charge will have been performed successfully, but the credit-card company respondsthat the transaction has failed, for whatever reason.

Errors from PayPal are returned in four parameters in the response:

L_ERRORCODE0

A numeric error code, which can referenced against PayPal’s error code list (there are

quite a few).

L_SHORTMESSAGE0

A short error message describing the problem.

L_LONGMESSAGE0


14 sur 17 05/10/2011 18:33

A longer error message describing the problem.

L_SEVERITYCODE0

The severity code. (I couldn’t find any useful documentation on this, and it doesn’t really

matter, so let’s put it aside.)

The 0 part of these parameters is an incrementing integer for multiple error message (1, 2,

etc.).

Here are some common errors you’ll run into:

10002

Authentication or authorization failed. This usually indicates invalid API

credentials, or credentials that do not match the type of environment you are working in

(such as a live or sandbox environment).

81***

Missing parameter. There are quite a few of these, all starting with 81. Each refers to

a specific required parameter that is missing from the request.

104**

Invalid argument. This indicates that one of the supplied parameters has an invalid

value. Each argument has specific errors, all starting with 104. A common one is 10413,

which means that the total cost of the cart items does not match the order’s amount (i.e.

the total amount parameter, AMT, does not equal the items’ total plus shipping, handling,

taxes and other charges).

How Do We Handle These Errors in Practice?

PayPal error messages vary and could contain private information that you do not want yourusers to see (such as an invalid merchant configuration). That being the case, showing PayPalerror messages directly to users is not advisable, even though some of them might be useful.

In most cases, I would do the following:

Set up a white-list array of errors that can be shown safely (such as a missing credit-card

number and expiration date);

1.

Check the response code against that array;2.

If the error message is not white-listed, then display a generic message, such as “An

error has occurred while processing your payment. Please try again in a few minutes, or

contact us if this is a recurring issue.”

3.

If an error falls outside of the white-listed array, I will also log it to a file on the server andsend an email to the administrator, with the full details so that someone is up to speed onpayment failures. In fact, logging PayPal requests and responses is good practice regardless oferrors, so that you can monitor and troubleshoot payment failures (I provide this option in the


15 sur 17 05/10/2011 18:33

commercial component that I mentioned at the beginning of this article).

Ready To Get Started With The PayPal API?

In this post, I’ve covered two of the most widely used API methods, as well as error handlingwith the PayPal API. This should be enough for you to get started using the most popularpayment platform online.

The PayPal API has many more methods and processes, more than can be covered in any onepost. Once you get up to speed on the basic methods, learning the others should be relativelystraightforward (even if somewhat exhausting). I hope this guide has given you a good headstart on using the API. If you have questions or comments, I would love to hear from you inthe comments!

Disclaimer: PayPal’s API is among the worst I’ve ever had to deal with. Inconsistencies,sometimes poor or conflicting documentation, unpredictable failures and account changes,and major differences between the live and sandbox versions all conspire to make the PayPalAPI quite a pain in the arse to work with. Over the years, I’ve taken my lumps from workingquite a bit with the PayPal API, and I’ve published the results of my hard-learned lessons as acommercial PHP PayPal API component on the source-code marketplace Binpress.

Front cover: Image source

(al)

Eran Galperin

I'm an entrepreneur and web developer. Formerly started Lionite, a web development shopand incubator, now I'm CTO on Binpress, a discovery service and marketplace forsource-code.

Learn more on Design:

Responsive DesignPhotoshop

TypographyMobile Design

Usability and UXDesign Legacy and Art

Learn more on Coding:


16 sur 17 05/10/2011 18:33

JavaScript & jQuery

WordPress TechniquesBack-End & Administration

HTML5 TutorialsCSS, CSS3

Bored?


17 sur 17 05/10/2011 18:33

Getting Started With the PayPal API - Smashing Coding

Documents

Transcript of Getting Started With the PayPal API - Smashing Coding