Medium 9781449396121

PayPal APIs: Up and Running: A Developer's Guide

Views: 2065
Ratings: (0)

If your web application's success depends on how quickly and easily users can make transactions, then PayPal is a solution you can't afford to overlook. This book helps you determine which PayPal option is best for your situation, and provides step-by-step instructions for implementing the payment method you choose—whether you're accepting money via the Web or mobile devices for products and services, donations, or anything else.

You'll find sample code written primarily in PHP and Objective-C, as well as use cases for executing options with PayPal's API. By the end of this book, you'll have a clear understanding of PayPal and how you can get the most out of its powerful features, no matter how much API programming experience you have.

  • Learn how to work with the PayPal API, and choose the right integration method for your project
  • Explore PayPal’s Express Checkout option, including its unique workflow and four methods of operation
  • Examine the Website Payment Pro method—with a focus on direct payments
  • Consider Adaptive Payments and learn how to set permission levels for their use
  • Use PayPal in your iOS or Android-based mobile app with the new Mobile Express Checkout method
  • Test your PayPal implementation with the sandbox

List price: $27.99

Your Price: $22.39

You Save: 20%


21 Slices

Format Buy Remix

1. The PayPal API


PayPal provides developer access to its payments system via its Name-Value Pair API, referred to as NVP API for the remainder of this book. The NVP API allows a merchant to access PayPal and accomplish the following tasks:

Accept PayPal during your checkout process via Express Checkout

Charge a credit card during a Direct Payment session

Capture previously authorized Express Checkout and Direct Payment payments

Reauthorize or void previous authorizations

Pay single or multiple recipients via Mass Payment

Issue full refunds or multiple partial refunds

Search transactions using a specified search criteria

Retrieve details of a specific transaction

Accept PayPal for multiparty payments

Accept PayPal for subscriptions or freemium models. (Freemium models offer a basic product or service free of charge, while charging a premium for advanced features. A good example is something like CCleaner: you can download it and use it free, and pay for a license if you want support. You can also make donations to future developmentand they accept PayPal for both.)


Checkout Process Workflows


Express Checkout is PayPals premier checkout solution. It allows a customer to check out on your site, log into his PayPal account, and purchase your goods or services. Express Checkout puts PayPal in charge of data security with regard to the customers billing and credit card information and removes that liability from the merchant. In this chapter, we will look at generic versus Express Checkout workflows, Express Checkout API operations, a simple Express Checkout integration, as well as an in-depth integration method.

Lets start by looking at the process flow of a typical checkout and an Express Checkout.

Figure2-1 shows the typical checkout flow a user experiences when buying goods or services online, which includes the following steps:

Customer clicks the checkout button on your shopping cart page.

Customer enters all shipping information.

Customer chooses her payment method and provides all the relevant billing and payment information.


Express Checkout Flow


To fully implement Express Checkout, you must allow your customers two entry points into the Express Checkout payment process. Figure2-3 outlines the complete checkout flow for Express Checkout.

Figure2-3.Complete Express Checkout flow

As you can see, customers can enter into the Express Checkout flow at either the Shopping Cart Checkout entry point (dotted arrow) or the Payment Methods entry point (solid arrow). Including both methods in your checkout routines is easy to implement.

Figure2-4 outlines the Checkout Entry Point, which requires the following steps:

Customer clicks the Check out with PayPal button.

Customer logs into PayPal.

Customer confirms shipping and billing information on PayPals site.

Customer is returned to your application for final review and clicks the Purchase button.

Customer is returned to a confirmation screen related to the purchase.

Figure2-4.Checkout Entry Point

Figure2-5 outlines the Payment Method Entry Point, which requires the following steps:


PayPal Express Checkout API Operations


The PayPal NVP API provides four key methods related to Express Checkout. These operations initialize the transaction, obtain the buyer information and handle the payment, and then complete the transaction. Table2-2 outlines these methods.

Table2-2.Express Checkout API operations

URL to the page on your website to which PayPal redirects after the buyer logs into PayPal and approves the payment successfully

URL to the page on your website to which PayPal redirects if the buyer cancels the transaction

Total amount of the order or your best estimate of the total (this should be as accurate as possible)

Lets break down each API operation into its smaller components and outline the related request and response fields.

SetExpressCheckout initializes the Express Checkout session. It allows you to pass variables that format how the PayPal pages look and specify where to redirect the buyers browser based upon success of the payment transaction.Table2-3 outlines the fields required for SetExpressCheckout requests, and Table2-4 outlines the field required for SetExpressCheckout responses.


Simple Express Checkout Integration


The simplest Express Checkout integration requires execution of only two PayPal API operations: SetExpressCheckout and DoExpressCheckoutPayment. For example, optionally, you can call GetExpressCheckoutDetails to error check the information provided to SetExpressCheckout against the form values and provide the customer a Confirm Transaction screen before finalizing the payment.

To set up an Express Checkout transaction, you must first invoke the SetExpressCheckout API to provide sufficient information to initiate the payment flow and redirect your customer to PayPal if the operation is successful.

When you initiate the Express Checkout transaction, you specify values in the SetExpressCheckout request, and then call the API. The values you specify control the PayPal page flow and options available to your customers.

Lets look at setting up a simple Express Checkout transaction.

First we need to specify the total dollar amount of the transaction, if known; otherwise, specify the subtotal. Refer to Table2-3s PAYMENTREQUEST_n_AMT field description for requirements and restrictions.


Express Checkout Integration


PayPal Express Checkout is the quickest and best solution for straight-out shopping cart checkouts. PayPals Integration Wizard, found at, helps you implement Express Checkout on your site. The wizard takes you through five configuration steps, described next.

The Integration Wizard starts by presenting a basic overview of what the tool will do. You can choose to watch the introduction or skip it at this point (Figure2-6).

Figure2-6.Express Checkout Integration Wizard opening screen

Step 1 allows you to choose the programming language you want to use for the integration (see Figure2-7). For the purposes of this example we are going to use PHP, but you can choose any of the following options:

Active Server Pages (ASP)



Java Server Pages (JSP)

Java SDK


You also are asked to specify the return and cancel URLs. The return URL is where the purchaser will be returned to once the transaction is completed. The cancel URL is where the purchaser is sent to if she cancels the checkout, typically back to your sites shopping cart. The payment type will be one of the following:


Overview of Direct Payment


PayPals Website Payments Pro allows you API access to two components: Express Checkout (covered in Chapter2) and Direct Payment. Direct Payment allows you to accept debit and credit cards directly from your site. Direct Payment, unlike Express Pay, requires the buyer to enter payment, billing, and shipping information, and does not require the buyer to have a PayPal Account. In addition, Website Payments Pro accounts do not show up as PayPal on your customers credit card statements: your companys name shows up instead.

Direct Payment allows your customers to pay via credit or debit cards during your checkout flow. This gives the seller complete control over the buyers transaction experience. When a buyer chooses to pay with a credit or debit card, he enters his card number and other information directly on your site. This arrangement makes the seller/merchant responsible for maintaining the security of the transaction, rather than PayPal, and it is highly recommended that you provide the checkout experience under an SSL connection. After the buyer confirms his order and clicks the Pay button, you complete the transaction by invoking the DoDirectPayment API operation.


Direct Payment Workflow



PayPal Direct Payment API Operations


The PayPal NVP API uses only one method related to Direct Payment: DoDirectPayment. This one method initializes the payment and returns the results all in one operation. Table3-1 outlines the DoDirectPayment request fields, and Table3-2 outlines the methods response fields.

Table3-1.DoDirectPayment request fields

Authorization: This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.

Sale: This is the default value, indicating that it is a final sale.

0: Do not receive FMF details (default)

1: Receive FMF details





Maestro *

Solo *

* If using Maestro or Solo, the CURRENCYCODE must be GBP. Additionally, either STARTDATE or ISSUENUMBER must be specified.

The card verification value, version 2. This field may or may not be required, depending on your merchant account settings.


Simple Direct Payment Integration


To implement a Direct Payment transaction, you need to invoke the DoDirectPayment API and provide information to identify the buyers credit or debit card and the amount of the payment. Setting up the transaction is accomplished through the following steps:

Specify the amount of the transaction, including the currency if it is not in U.S. dollars. You should specify the total amount of the transaction if it is known; otherwise, specify the subtotal.

AMT= amount


Specify the payment action. It is best practice to explicitly specify the payment action as one of the following values:


PAYMENTACTION= Authorization

Specify the IP address of the buyers computer:


Specify information about the card being used. You must specify the type of card as well as the account number:


ACCT= 1234567891011123

The type of credit/debit card being used, the card issuer, and the Payment Receiving Preferences setting on your PayPal Profile might require that you set the following fields as well:


Direct Payment Integrations



Overview of Adaptive Payments



PayPal Adaptive Payments API Operations Overview



Adaptive Payments Permission Levels


PayPals Adaptive Payments adds an additional layer of security and permission levels over other API functionality. Most of the Adaptive Payments API operations are available to all API callers, but some of the higher-level features are limited to those with advanced permission levels.

A merchant using a third-party Adaptive Payments application, at minimum, must have the same permission level required for the Adaptive Payments APIs called by the application. If, for example, your application supports chained payments but the merchant using it has a standard permission level, chained payments will not work for that merchant. Table4-2 outlines the current permission restrictions. This list is subject to change, and so I suggest referring to or for more information about current permission levels.

If you are distributing an application based upon Adaptive Payments, I highly recommend putting the required permission levels in your application distribution notes.


Adaptive Payments Application Workflows


Adaptive Payments facilitates payments between a sender and one or more receivers of that payment. You as the application owner and your application are the caller of the Adaptive Payments API operations. The application owner must have a PayPal business-level account, but senders and receivers can have a PayPal account of any type. Given the complexity and power for Adaptive Payments, you can be both the application owner and the receiver of payments. Outlined in Figure4-1, this is referred to as a simple payment, where a sender makes a payment to a single recipient. This type of payment is equivalent to what is done with Express Checkout.

Figure4-1.Adaptive Payments owner as recipient workflow

The Adaptive Payments API allows you and your application to act as an intermediary that facilitates payments for others, without you being a recipient of the funds, as outlined in Figure4-2. This is referred to as a parallel payment, in which the sender transmits a single payment to multiple recipients and can see who those recipients are. Parallel payments are commonly used in aggregated shopping, and allow a customer to order from multiple vendors with a single shopping cart.


Payment Approval and Payment Flows


Once a payment transaction via your application has been submitted, the sender of the payment must take an additional step and approve the transfer of funds. This can be one of four different payment approval types: Explicit, Preapproved, Implicit, or Guest Payments.

Explicit Payments require the sender to log into and approve each individual payment. This is the traditional method for paying via PayPal and is the only option a sender has, unless he has previously set up a preapproval agreement with you, or unless the sender is also the application provider. You can control the interaction between your application and PayPal during the transaction process by providing URLs for redirecting the sender, dependent on the situation. Figure4-5 outlines an Explicit Payment flow, which consists of the following steps:

Figure4-5.Explicit Payment flow

Your application sends a Pay request to PayPal.

PayPal responds with a key that you use to redirect the sender to PayPal.


Adaptive Payments API Operations in Depth


In the remaining pages of this chapter, we look at the following Adaptive Payments API operations in depth:


SetPaymentOptions API

ExecutePayment API

A complete list of all the defined Adaptive Payments API operations can be found at or

All payments made via Adaptive Payments have the same required fields. These are outlined in Table4-3.

Table4-3.Common required fields

PAY: Use this value if not using the request in combination with ExecutePaymentRequest.

CREATE: Use to set up payment instructions with a SetPaymentOptions request and then execute at a later time with an ExecutePaymentRequest.

PAY_PRIMARY: Used for chained payments only. This allows you to delay payments to secondary receivers at the time of the transaction and process only the primary receiver. To process the secondary payments, initiate ExecutePaymentRequest and pass the pay key obtained from the PayResponse.


Adaptive Payments Integration


PayPal provides an Integration Wizard for Adaptive Payments as well. It can be found at The wizard for Adaptive Payments contains only five steps.

The Integration Wizard starts by presenting an overview of the different types of payment methods you can implement via Adaptive Payments, as shown in Figure4-9.

Step 1 asks you for your programming language and whether you are working with the sandbox or a live implementation (see Figure4-10).

Step 2 allows you to download the paypalplatform.php code, shown in Example4-1 (see Figure4-11). This code contains all the core handlers for Adaptive Payments information. You will need to provide your API credentials in this file. For instructions on creating those credentials, refer to Creating an API Signature. Once you have completed your testing and are ready to go live, change $Env="sandbox" to $Env="live". This will change the endpoint to the live PayPal endpoint.


Load more


Print Book

Format name
File size
0 Bytes
Not Allowed
Not Allowed
Read aloud
Format name
Read aloud
In metadata
In metadata
File size
In metadata