Paypal Express Checkout 2012 Integration Guide

Express Checkout - 2012 - Integration Guide PP_ExpressCheckout_IG_2012 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Express-Checkout-2012-Integration-Guide-777937 paypal-express-checkout-2012-integration-guide-777937 paypal pdf

Open the PDF directly: View PDF .
Page Count: 78

PayPal Express Checkout Integration Guide

PayPal Express

Checkout Integration

Guide

Last updated: August 7, 2012

PayPal Express Checkout Integration Guide

Document Number: 100010.en_US-20120807

trademarks and brands are the property of their respective owners.

The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.

2449, Luxembourg, R.C.S. Luxembourg B 118 349

Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval

of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:

PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused

by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use

of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Express Checkout Integration Guide August 7, 2012 3

Contents

Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1 Getting Started With Express Checkout . . . . . . . . . . . 9

Key Features of Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

The Express Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Supported Countries and Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Relationship Between Express Checkout and Shopping Carts . . . . . . . . . . . . . . . 12

Express Checkout Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Implementing the Simplest Express Checkout Integration. . . . . . . . . . . . . . . . . . 13

Obtaining an Express Checkout Button and PayPal Mark. . . . . . . . . . . . . . . . 14

Before You Start Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Setting Up the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 16

Obtaining Express Checkout Transaction Details . . . . . . . . . . . . . . . . . . . . 18

Completing the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 19

Testing an Express Checkout Integration . . . . . . . . . . . . . . . . . . . . . . . . 20

Security Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Troubleshooting Your Express Checkout Integration . . . . . . . . . . . . . . . . . . . . 25

Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Encoding and Decoding Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Express Checkout Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Customizing the Express Checkout User Interface . . . . . . . . . . . . . . . . . . . 27

Settlements and Captured Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Recurring Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Mobile Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Parallel Payments With Express Checkout . . . . . . . . . . . . . . . . . . . . . . . 29

Fraud Management Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Contents

4August 7, 2012 Express Checkout Integration Guide

Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Dynamic Images Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Express Checkout Instant Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Express Checkout Building Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Express Checkout Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Express Checkout API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Express Checkout Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Express Checkout Token Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 2 Express Checkout User Interface Requirements . . . . . .35

Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Checkout Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Payment Option Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

PayPal Button and Logo Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Express Checkout Image Flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Express Checkout Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Payment Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Chapter 3 Related API Operations . . . . . . . . . . . . . . . . . . .39

Sale Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 39

Authorization Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . 39

Order Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . 40

Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Tracking Failed or Pending Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 4 Integrating Express Checkout With PayPal SDKs . . . . . .45

Chapter 5 Going Live With Your Express Checkout Integration . . . .47

Chapter A Obtaining API Credentials . . . . . . . . . . . . . . . . . .49

Creating an API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating an API Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Encrypting Your Certificate Into PKCS12 Format . . . . . . . . . . . . . . . . . . . . 51

Importing Your Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter B PayPal Name-Value Pair API Basics . . . . . . . . . . . . .55

PayPal API Client-Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Express Checkout Integration Guide August 7, 2012 5

Contents

PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 56

UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

NVP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Specifying an API Credential Using Signatures . . . . . . . . . . . . . . . . . . . . . 59

URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter C PayPal SOAP API Basics . . . . . . . . . . . . . . . . . .65

PayPal WSDL/XSD Schema Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

PayPal SOAP API Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

SOAP RequesterCredentials: Username, Password, Signature, and Subject. . . . . . . . 67

SOAP Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

SOAP Request Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

SOAP Message Style: doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Response Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

CorrelationID for Reporting Problems to PayPal. . . . . . . . . . . . . . . . . . . . . . . 75

UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Date/Time Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Core Currency Amount Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Contents

6August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 7

Preface

About This Guide

This document describes basic Express Checkout integration.

Intended Audience

This document is for merchants and developers who want to get started implementing Express

Checkout.

Where to Go for More Information

-Express Checkout Advanced Features Guide

-Name-Value Pair API Developer Guide

-SOAP API Developer Reference

-Merchant Setup and Administration Guide

Documentation Feedback

Help us improve this guide by sending feedback to:

documentationfeedback@paypal.com

Preface

Documentation Feedback

8August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 9

1Getting Started With Express

Checkout

The Express Checkout button gives buyers another way to pay, and it complements your

existing payment solution. Online shoppers appreciate the convenience and security of PayPal,

where they can pay with their PayPal balance, bank account, or credit card.

Key Features of Express Checkout

Express Checkout is a fast, easy way for buyers to pay with PayPal. Express Checkout

eliminates one of the major causes of checkout abandonment by giving buyers all the

transaction details at once, including order details, shipping options, insurance choices, and

tax totals.

Studies show that adding the Express Checkout button to your website can increase your sales

up to 18 percent. The following web page shows the Express Checkout button side-by-side

with an existing checkout button:

Getting Started With Express Checkout

Key Features of Express Checkout

10 August 7, 2012 Express Checkout Integration Guide

Use Express Checkout to:

-Accept payments from any PayPal account.

-Eliminate the need for customers to enter personal information, including shipping, billing,

or payment information.

-Keep customers on your site after completing the transaction.

-Sign up customers to make payments at regular intervals.

Express Checkout Integration Guide August 7, 2012 11

Getting Started With Express Checkout

Key Features of Express Checkout

-See more at: https://merchant.paypal.com/cgi-

bin/marketingweb?cmd=_render-

content&content_ID=merchant/express_checkout&nav=2.1.5

The Express Checkout Experience

Express Checkout makes it easier for buyers to pay online. It also enables you to accept PayPal

while retaining control of the buyer and the overall checkout flow.

Consider your buyers’ experience before implementing Express Checkout. A generic flow

probably has the following sequence of pages:

A generic checkout flow

In a typical checkout flow, a buyer:

1. Checks out from the shopping cart page

2. Provides shipping information

3. Chooses a payment option and provides billing and payment information

4. Reviews the order and pays

5. Receives an order confirmation

In an Express Checkout flow, a buyer still checks out at the beginning of the flow. However,

the buyer does not enter shipping, billing, or payment information, because PayPal provides

the stored information. This simplifies and expedites the checkout process.

The following diagram shows the Express Checkout flow:

Express Checkout flow

In the Express Checkout flow, the buyer:

1. Chooses Express Checkout by clicking Check out with PayPal

2. Logs into PayPal to authenticate his or her identity

Getting Started With Express Checkout

Relationship Between Express Checkout and Shopping Carts

12 August 7, 2012 Express Checkout Integration Guide

3. Reviews the transaction on PayPal

NOTE:Optionally, (not shown in the diagram), the buyer can then proceed to review the

order on your site. You can also include other checkout steps, including upselling

on your Review Order page.

4. Confirms the order and pays from your site

5. Receives an order confirmation

Supported Countries and Currencies

Express Checkout enables you to accept payments from many countries and regions. The

checkout flow is also localized for a subset of countries.

For information about the countries and currencies that Express Checkout supports, see PayPal

Offerings Worldwide. For information about localized flows and additional country information,

see Send and Receive Payments Securely Worldwide.

Relationship Between Express Checkout and Shopping Carts

If you do not have your own shopping cart and have not integrated Express Checkout with

your website, you might consider using a third-party shopping cart. A shopping cart is

software that lets buyers put items in a basket and calculates totals during checkout.

PayPal partners with a wide variety of shopping carts, all of which are PayPal compatible and

provide secure purchases for your buyers. The shopping cart vendor provides instructions for

integrating their shopping cart on your website. See the PayPal Partner Directory

(https://www.paypal-

marketing.com/emarketing/partner/directory/directory.page?type=Shopp

ing+Cart#mode=dir&dir%5Bops%5D=either&dir%5Bkey%5D=Keyword+term&dir%

5Btyp%5D%5B%5D=1&dir%5Bind%5D%5B%5D=0&dir%5Brod%5D%5B%5D=1&dir%5Brod

%5D%5B%5D=2) for available shopping carts.

IMPORTANT:If you choose a shopping cart, do not contact PayPal. PayPal has no authority

over a shopping cart vendor and cannot help you resolve issues that might

arise from the integration with or use of a third-party shopping cart.

Express Checkout Prerequisites

Prerequisites to Express Checkout include the kind of PayPal accounts you need as well as the

required programming skills and experience. If you want to use Express Checkout but do not

have the required skills or experience, you should consider using PayPal Payments Standard

(previously known as Website Payments Standard) or a shopping cart provided by PayPal or a

third party.

Express Checkout Integration Guide August 7, 2012 13

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

To use Express Checkout, you must have:

-A Business or Premier account. A Business or Premier account enables you to become a

merchant for whom PayPal collects money from buyers for goods or services. PayPal

manages these transactions and charges you a small fee and a percentage of the amount

collected from the buyer for each transaction.

-A Sandbox account with two test accounts. The PayPal Sandbox provides an environment

that simulates PayPal, in which you execute your Express Checkout integration without

actually exchanging money. One of your test accounts represents you as the merchant, or

seller using Sandbox terminology, and the other test account represents a buyer. Your

testing is not restricted to just two accounts; however, you must have a Sandbox account to

create test accounts and perform actual testing.

-HTML experience. Probably, you already have an existing website and may have already

implemented a checkout experience for the goods or services you sell on your site. You

will need to add the Pay with Express Checkout button, as well as another button, called

the Express Checkout mark, to your web pages. The Pay with Express Checkout button

initiates the PayPal checkout flow. The mark enables the buyer to choose Express

Checkout from the page that specifies the payment method, called the payment page, in

case the buyer did not start with Pay with Express Checkout.

-Programming experience. When the buyer clicks a button, you must provide code that

requests a PayPal server to set up or process the transaction and code to handle the

response. PalPal provides an easy-to-user interface built on the HTTP request-response

model, as well as a more complicated SOAP web services interface. PayPal also provides

Software Development Kits (SDKs) that provide an interface in various programming

languages, such as PHP, Ruby, Java, and .NET languages like C#. Although you need not

know a specific language, you will need to understand programming logic, especially the

request-response model, error handling, and the nuances of writing application-level code.

NOTE:If the description of the programming experience prerequisite seems confusing

(like “what’s an interface?”), you can still use Express Checkout provided by a

shopping cart vendor, including PayPal, or use another PayPal product, such as

PayPal Payments Standard. You should not attempt to integrate Express Checkout

on your own unless you have sufficient programming experience. A programmer

or developer will find Express Checkout easy; a complete novice could lose sales

or goods and not even know it.

Implementing the Simplest Express Checkout Integration

The simplest Express Checkout integration requires you to set up a PayPal button and call the

following PayPal API operations when your buyer clicks the button: SetExpressCheckout,

DoExpressCheckoutPayment, and typically, GetExpressCheckoutDetails.

You must also enable the buyer to select PayPal as the payment method after the buyer starts

to check out. Thus, you must call these API operations from two places. You must perform

these API operations on your checkout page and on your payment method page.

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

14 August 7, 2012 Express Checkout Integration Guide

Related information:

"Express Checkout Flow" on page 35

Obtaining an Express Checkout Button and PayPal Mark

PayPal requires that you use the Check out with PayPal button and the PayPal mark image

hosted on secure PayPal servers. When the images are updated, the changes appear

automatically in your application.

You must put the Express Checkout button on your checkout page. To obtain an Express

Checkout Button:

1. Go to the PayPal Button Code page (https://www.paypal.com/express-checkout-buttons).

A page similar to the following one appears:

2. Select and copy the image source text from the window below the button.

3. Paste the image source text into your checkout page’s HTML source where you want the

button to appear on your page.

Result:

When you display your checkout page in the browser, the Check out with PayPal button

should appear:

Express Checkout Integration Guide August 7, 2012 15

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

After Completing This Task:

You will need to place the PayPal mark image on your payment page. The instructions for

obtaining this image are similar to the instructions for obtaining the button. The mark is found

on the same Button Code page (https://www.paypal.com/express-checkout-buttons) as the Express

Checkout button:

Before You Start Coding

If you are not familiar with how PayPal APIs work, read this topic. It provides the minimum

information you need to be successful using the PayPal Name-Value Pair API.

PayPal API Client-Server Architecture

The PayPal API uses a client-server model in which your website is a client of the PayPal

server.

A page on your website initiates an action on a PayPal API server by sending a request to the

server. The PayPal server responds with a confirmation that the requested action was taken or

indicates that an error occurred. The response might also contain additional information

related to the request. The following diagram shows the basic request-response mechanism.

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

16 August 7, 2012 Express Checkout Integration Guide

For example, you might want to obtain the buyer’s shipping address from PayPal. You can

initiate a request specifying an API operation to obtain buyer details. The response from the

PayPal API server contains information about whether the request was successful. If the

operation succeeds, the response contains the requested information. In this case, the response

contains the buyer’s shipping address. If the operation fails, the response contains one or more

error messages.

Related information:

"Creating an NVP Request" on page 58

"Responding to an NVP Response" on page 62

Obtaining API Credentials

To use the PayPal API, you must have API credentials that identify you as a PayPal Business

or Premier account holder who is authorized to perform various API operations. Although you

can use either an API signature or a certificate for credentials, PayPal recommends you use a

signature.

IMPORTANT:Although you can have both a signature and certificate, you cannot use both at

the same time.

Setting Up the Express Checkout Transaction

To set up an Express Checkout transaction, you must invoke the SetExpressCheckout API

operation to provide sufficient information to initiate the payment flow and redirect to PayPal

if the operation was successful.

This example assumes that you have set up the mechanism you will use to communicate with

the PayPal server and have a PayPal Business account with API credentials. It also assumes

that the payment action is a final sale.

When you set up an 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 the options available to you and your buyers. You should start by setting

up a standard Express Checkout transaction, which can be modified to include additional

options.

To set up the simplest standard Express Checkout transaction:

Express Checkout Integration Guide August 7, 2012 17

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

1. Specify that you want to execute the SetExpressCheckout API operation and the

version you want to use.

METHOD=SetExpressCheckout

VERSION=XX.0

2. Specify your API credentials.

Use the following parameters for a signature:

USER=API_username

PWD=API_password

SIGNATURE=API_signature

In the Sandbox, you can always use the following signature:

USER=sdk-three_api1.sdk.com

PWD=QFZCWN5HZM8VBG7Q

SIGNATURE=A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

3. Specify the amount of the transaction; include the currency if it is not in US dollars.

Specify the total amount of the transaction if it is known; otherwise, specify the subtotal.

Regardless of the specified currency, the format must have a decimal point with exactly

two digits to the right and an optional thousands separator to the left, which must be a

comma.

For example, EUR 2.000,00 must be specified as 2000.00 or 2,000.00. The specified amount

cannot exceed USD $10,000.00, regardless of the currency used.

PAYMENTREQUEST_0_AMT=amount

PAYMENTREQUEST_0_CURRENCYCODE=currencyID

4. Specify the return URL.

The return URL is the page to which PayPal redirects your buyer’s browser after the buyer

logs into PayPal and approves the payment. Typically, this is a secure page

(https://...) on your site.

NOTE:You can use the return URL to piggyback parameters between pages on your site.

For example, you can set your Return URL to specify additional parameters using

the https://www.yourcompany.com/page.html?param=value... syntax. The

parameters become available as request parameters on the page specified by the

Return URL.

RETURNURL=return_url

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

18 August 7, 2012 Express Checkout Integration Guide

5. Specify the cancel URL.

The cancel URL is the page to which PayPal redirects your buyer’s browser if the buyer

does not approve the payment. Typically, this is the secure page (https://...) on your

site from which you redirected the buyer to PayPal.

NOTE:You can pass SetExpressCheckout request values as parameters in your URL

to have the values available, if necessary, after PayPal redirects to your URL.

CANCELURL=cancel_url

6. Specify the payment action.

Although the default payment action is a Sale, it is a best practice to explicitly specify the

payment action as one of the following values:

PAYMENTREQUEST_0_PAYMENTACTION=Sale

After Completing This Task:

If calling the SetExpressCheckout API was successful, redirect the buyer’s browser to

PayPal and execute the _express-checkout command using the token returned in the

SetExpressCheckout response.

NOTE:The following example uses the PayPal Sandbox server:

https://www.sandbox.paypal.com/webscr

?cmd=_express-checkout&token=tokenValue

Obtaining Express Checkout Transaction Details

To obtain details about an Express Checkout transaction, you can invoke the

GetExpressCheckoutDetails API operation.

This example assumes that PayPal redirects to your buyer’s browser with a valid token after

the buyer reviews the transaction on PayPal.

Although you are not required to invoke the GetExpressCheckoutDetails API operation,

most Express Checkout implementations take this action to obtain information about the

buyer. You invoke the GetExpressCheckoutDetails API operation from the page

specified by return URL, which you set in your call to the SetExpressCheckout API.

Typically, you invoke this operation as soon as the redirect occurs and use the information in

the response to populate your review page.

To obtain a buyer’s shipping address and Payer ID:

1. Specify that you want to execute the GetExpressCheckoutDetails API operation and

the version you want to use.

Express Checkout Integration Guide August 7, 2012 19

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

METHOD=GetExpressCheckoutDetails

VERSION=XX.0

2. Specify your API credentials.

Use the following parameters for a signature:

USER=API_username

PWD=API_password

SIGNATURE=API_signature

3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site.

PayPal returns the token to use in the token HTTP request parameter when redirecting to

the URL you specified in your call to the SetExpressCheckout API.

TOKEN=tokenValue

4. Execute the GetExpressCheckoutDetails API to obtain information about the buyer.

5. Access the fields in the GetExpressCheckoutDetails API response.

NOTE:Only populated fields are returned in the response.

Completing the Express Checkout Transaction

To complete an Express Checkout transaction, you must invoke the

DoExpressCheckoutPayment API operation.

This example assumes that PayPal redirects your buyer’s browser to your website with a valid

token after you call the SetExpressCheckout API. Optionally, you may call the

GetExpressCheckoutDetails API before calling the DoExpressCheckoutPayment

API.

In the simplest case, you set the total amount of the order when you call the

SetExpressCheckout API. However, you can change the amount before calling the

DoExpressCheckoutPayment API if you did not know the total amount when you called

the SetExpressCheckout API.

This example assumes the simplest case, in which the total amount was specified in the return

URL when calling the SetExpressCheckout API. Although you can specify additional

options, this example does not use any additional options.

To execute an Express Checkout transaction:

1. Specify that you want to execute the DoExpressCheckoutPayment API operation and

the version you want to use.

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

20 August 7, 2012 Express Checkout Integration Guide

METHOD=DoExpressCheckoutPayment

VERSION=XX.0

2. Specify your API credentials.

Use the following parameters for a signature:

USER=API_username

PWD=API_password

SIGNATURE=API_signature

3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site.

PayPal returns the token to use in the token HTTP request parameter when redirecting to

the URL you specified in your call to the SetExpressCheckout API.

TOKEN=tokenValue

4. Specify the Payer ID returned by PayPal when it redirects the buyer’s browser to your site.

PayPal returns the Payer ID to use in the token HTTP request parameter when redirecting

to the URL you specified in your call to the SetExpressCheckout API. Optionally, you

can obtain the Payer ID by calling the GetExpressCheckoutDetails API.

PAYERID=id

5. Specify the amount of the order including shipping, handling, and tax; include the currency

if it is not in US dollars.

Most of the time, this will be the same amount as you specified in your

SetExpressCheckout call, adjusted for shipping and taxes.

PAYMENTREQUEST_0_AMT=amount

PAYMENTREQUEST_0_CURRENCYCODE=currencyID

6. Specify the same payment action that you specified in SetExpressCheckout.

PAYMENTREQUEST_0_PAYMENTACTION=Sale

Testing an Express Checkout Integration

You can test your Express Checkout integration in the Sandbox.

This example shows how to simulate your web pages using HTTP forms and supplying the

values for API operations from these forms. You can use this strategy for your initial testing;

however, for more complete testing, you need to replace these forms with your web pages

containing your actual code.

Express Checkout Integration Guide August 7, 2012 21

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

The following diagram shows the Express Checkout execution flow, which uses the Sandbox

as the API server. The pages on the left represent your site.

The following steps match the circled numbers in the diagram. Perform the actions in each

step to test Express Checkout.

1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox.

To invoke the API, set form fields whose names match the NVP names of the fields you want

to set, specify their corresponding values, and then post the form to a PayPal Sandbox server,

such as https://api-3t.sandbox.paypal.com/nvp, as shown in the following

example:

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

22 August 7, 2012 Express Checkout Integration Guide

<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION

value=Sale>

<input type=hidden name=RETURNURL

value=https://www.YourReturnURL.com>

<input type=hidden name=CANCELURL

value=https://www.YourCancelURL.com>

</form>

NOTE:Use an API username from a Sandbox business test account for which a signature

exists. See the Test Certificates tab of the Sandbox to obtain a signature. If you are not

using a signature, you must use a different Sandbox server.

IMPORTANT:This example does not establish a secure connection and should not be used

live on paypal.com.You must protect the values for USER, PWD, and

SIGNATURE in your implementation. Consider storing these values in a secure

location other than your web server document root and setting the file

permissions so that only the system user that executes your ecommerce

application can access it.

2. Review the response string from the SetExpressCheckout API operation.

PayPal responds with a message, such as the one shown below. Note the status, which

should include ACK set to Success, and a token that is used in subsequent steps.

TIMESTAMP=2007%2d04%2d05T23%3a23%3a07Z

&CORRELATIONID=63cdac0b67b50

&ACK=Success

&VERSION=XX%2e000000

&BUILD=1%2e0006

&TOKEN=EC%2d1NK66318YB717835M

3. If the operation was successful, use the token and redirect your browser to the Sandbox to

Express Checkout Integration Guide August 7, 2012 23

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

https://www.sandbox.paypal.com/cgi-bin/webscr?

cmd=_express-checkout

&token=EC-1NK66318YB717835M

You may need to decode the URL, which is the opposite of URL encoding, by replacing

hexadecimal codes with ASCII codes; for example, you may need to replace %2d in the

token with a hyphen ( - ).

You must log in to https://developer.paypal.com before you log in to a Sandbox

test account. You then log in to the test account that represents the buyer, not the seller’s

business test account that represents you as the merchant.

4. After logging into the buyer test account, confirm the details.

When you confirm, the Sandbox redirects your browser to the return URL you specified

when invoking the SetExpressCheckout API operation, as in the following example:

http://www.YourReturnURL.com/

?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8

5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation

on the Sandbox:

<form method=post action=https://api-3t.sandbox.paypal.com/nvp

</form>

If the operation was successful, the GetExpressCheckoutDetails API returns

information about the payer, such as the following information:

Getting Started With Express Checkout

Implementing the Simplest Express Checkout Integration

24 August 7, 2012 Express Checkout Integration Guide

TIMESTAMP=2007%2d04%2d05T23%3a44%3a11Z

&CORRELATIONID=6b174e9bac3b3

&ACK=Success

&VERSION=XX%2e000000

&BUILD=1%2e0006

&TOKEN=EC%2d1NK66318YB717835M

&EMAIL=YourSandboxBuyerAccountEmail

&PAYERID=7AKUSARZ7SAT8

&PAYERSTATUS=verified

&FIRSTNAME=...

&LASTNAME=...

&COUNTRYCODE=US

&BUSINESS=...

&PAYMENTREQUEST_0_SHIPTONAME=...

&PAYMENTREQUEST_0_SHIPTOSTREET=...

&PAYMENTREQUEST_0_SHIPTOCITY=...

&PAYMENTREQUEST_0_SHIPTOSTATE=CA

&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US

&PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME=United%20States

&PAYMENTREQUEST_0_SHIPTOZIP=94666

&PAYMENTREQUEST_0_ADDRESSID=...

&PAYMENTREQUEST_0_ADDRESSSTATUS=Confirmed

6. Invoke a form on your site that invokes the DoExpressCheckoutPayment API operation

on the Sandbox:

<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION

value=Authorization>

</form>

Express Checkout Integration Guide August 7, 2012 25

Getting Started With Express Checkout

Troubleshooting Your Express Checkout Integration

7. Review the response string from the DoExpressCheckoutPayment API operation.

If the operation was successful, the response should include ACK set to Success, as

follows:

TIMESTAMP=2007%2d04%2d05T23%3a30%3a16Z

&CORRELATIONID=333fb808bb23

ACK=Success

&VERSION=XX%2e000000

&BUILD=1%2e0006

&TOKEN=EC%2d1NK66318YB717835M

&PAYMENTREQUEST_0_TRANSACTIONID=043144440L487742J

&PAYMENTREQUEST_0_TRANSACTIONTYPE=expresscheckout

&PAYMENTREQUEST_0_PAYMENTTYPE=instant

&PAYMENTREQUEST_0_ORDERTIME=2007%2d04%2d05T23%3a30%3a14Z

&PAYMENTREQUEST_0_AMT=19%2e95

&PAYMENTREQUEST_0_CURRENCYCODE=USD

&PAYMENTREQUEST_0_TAXAMT=0%2e00

&PAYMENTREQUEST_0_PAYMENTSTATUS=Pending

&PAYMENTREQUEST_0_PENDINGREASON=authorization

&PAYMENTREQUEST_0_REASONCODE=None

Security Issues

You must always be concerned with protecting sensitive data. This not only includes your API

credentials, but also any data exposed in a client’s browser, such as data about the transaction

stored in cookies.

-In the simplest examples, such as the ones provided by PayPal to demonstrate Express

Checkout usage, the API credentials may be exposed. Thus, if you copy code from

examples or SDKs, you should always review your website for security issues and correct

them before you go live with your website.

-Encrypt all saved information related to the PayPal transaction. For example, if you keep

order status information in a cookie, make sure the information is encrypted.

-Use a secure transmission protocol, such as HTTPS to transfer information between your

site and PayPal. Do not use HTTP or insecure cURL.

Troubleshooting Your Express Checkout Integration

If you have trouble with your integration, there are several things you can check first. If you

try them yet continue to have problems, you can also contact Merchant Technical Support

(MTS).

If you cannot resolve the issue yourself, you will need to gather some basic information before

contacting MTS, including a log of the actions that led to the error. You can contact MTS at

https://www.paypal.com/mts.

Getting Started With Express Checkout

Troubleshooting Your Express Checkout Integration

26 August 7, 2012 Express Checkout Integration Guide

Error Handling

The response message contains an ACK value. Unless ACK=Success, you must check further

for an error or warning message.

You must check each response from the PayPal server for an indication that an error occurred.

Because there are several warning and failure values, the safest way to check the response is to

check for ACK=Success. If the ACK returns any other value, you must examine the response

for error numbers and messages.

A non-successful response can contain more than one error number and message. Error fields

start with L_ERRORCODEn, where n, starting from 0, identifies a unique error in the response.

There are two messages for each error number, L_SHORTMESSAGEn and L_LONGMESSAGEn,

where n corresponds with n in L_ERRORCODEn.

IMPORTANT:Because error numbers are not guaranteed to be unique, you must use both the

number and the messages to determine the appropriate action to take when an

error occurs.

Some errors are transitory in nature and you can retry the operation; for example, an error that

indicates a problem with PayPal. If the problem persists for more than an hour, it is probably

related to your Express Checkout implementation because PayPal servers are up and running

almost all of the time.

Some errors indicate problems with the buyer’s account; for example, the funding source is no

longer valid or the buyer’s account is restricted in some way. The error message has enough

information to create a message on your website that tells the buyer how to resolve the issue.

Often, you simply prompt the buyer to choose a different funding source. Because these kinds

of problems can indicate a risk issue, you do not want to ship goods until the issue has been

resolved.

Other errors indicate a problem with your integration, such as accepting invalid input on your

website and passing it in your request message to PayPal. You need to perform sufficient

testing using the Sandbox to prevent problems from arising after going live.

Timeouts

A timeout situation occurs if an API operation’s completion status is not known or the buyer

navigates away from the page that receives the response before PayPal completes the

operation. You must not ship goods before receiving a valid transaction ID, which indicates

that PayPal accepted the payment.

It is safe to execute the API operation again if the status is not known. In the case of

DoExpressCheckout, you can execute GetExpressCheckoutDetails and examine the

CheckoutStatus field. Any value other than PaymentCompleted indicates that the

payment has not completed. You should not ship goods until you receive a valid transaction ID

from calling either DoExpressCheckoutPayment or GetExpressCheckoutDetails.

Express Checkout Integration Guide August 7, 2012 27

Getting Started With Express Checkout

Express Checkout Features

Logging API Operations

You should log basic information from the request and response messages of each PayPal API

operation you execute. You must log the Correlation ID from the response message, which

identifies the API operation to PayPal and which must be provided to Merchant Technical

Support if you need their assistance with a specific transaction.

All responses to PayPal API operations contain information that may be useful for debugging

purposes. In addition to logging the Correlation ID from the response message, you can log

other information, such as the transaction ID and timestamp, to enable you to review a

transaction on the PayPal website or through the API. You could implement a scheme that logs

the entire request and response in a “verbose” mode; however, you should never log the

password from a request.

Encoding and Decoding Values

You must encode and decode all values sent in API operations. Only encode the value and not

the name in NVP and not the tags in SOAP.

You must encode all request field values in a request to PayPal and decode all field values in

the response. You must encode and decode individual values; do not encode or decode the

entire message. Browsers often attempt to encode and decode messages that are redirected to

or from them; however, you must verify that encoding and decoding is done correctly and only

to field values.

Express Checkout Features

Express Checkout features include ways to configure Express Checkout API reqeusts, ways to

customize the PayPal checkout pages, and additional settings you can specify.

Customizing the Express Checkout User Interface

You can customize the appearance of the PayPal Express Checkout pages. Some changes alter

the checkout flow.

Express Checkout includes options for presenting the checkout pages that appear when the

buyer logs into PayPal during checkout. Some of them make the PayPal pages look like your

own pages, giving the customer a consistent visual presentation:

-Logo to display

-Colors for the background and border

-Language in which PayPal content is displayed

-Your customer service number

Getting Started With Express Checkout

Express Checkout Features

28 August 7, 2012 Express Checkout Integration Guide

NOTE:All of the above customizations can be set in your profile. You set them in an Expresss

Checkout API operation only when you want to override the default provided by your

profile.

Other options streamline the flow, by allowing the buyer to complete the payment on PayPal,

or change the kind of information that is presented during checkout. On the PayPal Review

page, you can:

-Include per-item details

-Include tax, insurance, shipping costs, and shipping discounts

-Indicate whether the total displayed on the page is exact or an estimate before items such as

tax and shipping costs

-Display a note to the buyer; for example, a note identifying the shipping options are

available

-Allow your buyer to specify instructions to you

-Assign an invoice number to a payment

Other features may be used in specialized cases:

-Shipping address display and usage

-Choices for gift wrapping

-Buyer consent to receive your promotional materials

-Survey questions

Settlements and Captured Payments

Express Checkout enables you to collect a payment immediately or capture the payment later;

for example, when you ship the goods. Express Checkout provides several ways to set up a

transaction for later capture.

Often, you accept a payment and ship goods immediately, which is referred to as a sale. In

addition to immediate payments, Express Checkout allows you to authorize payments to be

captured later, which is referred to as an authorization. An authorization is useful, for

example, when you want to reserve a buyer’s funds pending the shipment of goods; the actual

payment is captured when the goods are shipped. An authorization can be reauthorized one

time if necessary; for example, when you are unable to ship within 3 days of the authorization.

Express Checkout provides an additional option, called an order, which you use when a single

authorization is insufficient. You can create multiple authorizations and capture them as part

of the same order. This is useful, for example, when an order is split into multiple shipments

and you need to capture a payment each time part of the order is shipped.

Refunds

You can issue full or partial refunds up to the full amount of the payment. You can make a

refund for payments captured initially or as part of a later settlement.

Express Checkout Integration Guide August 7, 2012 29

Getting Started With Express Checkout

Express Checkout Features

You cannot make a refund if the transaction occurred after the refund period has passed, which

typically is 60 days.

Related information:

"Issuing Refunds" on page 41

Recurring Payments

Express Checkout provides recurring payments, which enables you to manage subscriptions

and other payments on a fixed schedule. If you have permission from PayPal to use reference

transactions, you can provide variable payments on a varying schedule.

When you support recurring payments for a buyer, you create a recurring payments profile.

The profile contains information about the recurring payments, including details for an

optional trial period and a regular payment period. Both periods contain information about the

payment frequency and payment amounts, including shipping and tax, if applicable.

After creating a profile, PayPal automatically queues payments based on the billing start date,

billing frequency, and billing amount. Payments reoccur until the profile expires, there are too

many failed payments to continue, or you cancel the profile.

Permission to allow recurring payments is established by the buyer setting up a billing

agreement with the merchant on PayPal. For Express Checkout, the billing agreement can be

established either in advance or when the buyer first makes a purchase; in either case, it occurs

when you call Express Checkout API operations.

Recurring Payments Using Reference Transactions

Recurring payments using reference transactions is an alternative, which enables you to handle

payments for varying amounts of money on a varying schedule. A reference transaction is a

financial transaction from which subsequent transactions can be derived; for example, a buyer

can make a purchase on your site and the PayPal transaction ID, called a reference transaction

ID, can later be used to initiate another transaction.

Mobile Express Checkout

PayPal supports several implementations of Mobile Express Checkout. You can provide a

complete mobile website, or you can create a mobile phone app in which the checkout button

is integrated into the app itself or is on your mobile website.

On mobile devices, Express Checkout provides payment pages tailored for faster checkout and

for smaller mobile screens and keyboards. You can either set up the experience so that the

buyer pays on your site or pays on PayPal.

Parallel Payments With Express Checkout

Parallel payments enable buyers to pay multiple merchants in an Express Checkout flow. This

feature is not available for Mobile Express Checkout.

Getting Started With Express Checkout

Express Checkout Features

30 August 7, 2012 Express Checkout Integration Guide

In parallel payments, a merchant acts as marketplace host. Consider an online travel agency.

The buyer purchases airline tickets and makes reservations from various merchants such as

hotels, car rental agencies, and entertainment venues hosted on the site. By implementing

parallel payments through Express Checkout, the marketplace host accepts PayPal as a

payment method. The host also provides the buyer with a consolidated order on the PayPal

Review page, summarizing expenses, itineraries, and other supporting information. Buyers see

travel information, including cancellation fees, directly from the supplier on the Transaction

Details page and in an email message.

Fraud Management Filters

Fraud Management Filters (FMF) provide you filters that identify potentially fraudulent

transactions. There are 2 categories of filters:

-Basic filters screen against data such as the country of origin and the value of transactions.

PayPal provides basic filters for Business accounts and Website Payments Pro accounts.

-Advanced filters screen data such as credit card and addresses information, lists of high-

risk indicators, and additional transaction characteristics. Website Payments Pro merchants

can upgrade to use these filters.

NOTE:Using advanced filters might incur additional charges.

For more information about Fraud Management Filters, see Fraud Management Filters

Event Notification

In most cases, you can use PayPal API operations to determine the information you need about

a transaction. However, there may be some cases in which you must set up IPN; for example,

when you need automatic notification about actions, such as disputes and their resolution.

IPN is a message service that PayPal uses to notify you about events, such as:

-Instant payments, including Express Checkout, Adaptive Payments, and direct credit card

payments, and authorizations, which indicate a sale whose payment has not yet been

collected

-eCheck payments and associated status, such as pending, completed, or denied, and

payments pending for other reasons, such as those being reviewed for potential fraud

-Recurring payment and subscription actions

-Chargebacks, disputes, reversals, and refunds associated with a transaction

For more information about IPN, see Instant Payment Notification Guide

Express Checkout Integration Guide August 7, 2012 31

Getting Started With Express Checkout

Express Checkout Building Blocks

Dynamic Images Overview

Dynamic images enables PayPal to tailor the Express Checkout button for a campaign or

event. This feature is not supported for Mobile Express Checkout.

When you participate in a PayPal campaign or event, PayPal automatically updates the image

to reflect the campaign information. When the campaign is over, PayPal restores the default

image. You are not responsible for scheduling or making changes to your website application

code before, during, or after the campaign. These activities are all handled for you when you

set up the dynamic image.

Express Checkout Instant Update

The instant update feature enables you to create a message that responds with shipping

information, allowing you to provide location-based shipping, insurance, and tax information.

It is not available for Mobile Express Checkout.

You specify a URL that provides the information, which is based on the buyer’s address which

is stored on PayPal. You are not allowed to see the buyer’s actual address.

Express Checkout Building Blocks

You implement Express Checkout flows with Express Checkout buttons, PayPal API

operations, PayPal commands, and tokens.

The following conceptual diagram identifies the building blocks that you use to integrate

Express Checkout on your website:

Getting Started With Express Checkout

Express Checkout Building Blocks

32 August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration

A token is a value assigned by PayPal that associates the execution of API operations and

commands with a specific instance of a user experience flow.

NOTE:Tokens are not shown in the diagram.

Express Checkout Buttons

PayPal provides buttons and images for you to place on your website.

To implement the Express Checkout shopping cart experience, place the following button on

your Shopping Cart page:

To implement PayPal as a payment option, which is part of the Express Checkout experience,

associate the PayPal mark image with your payment options. PayPal recommends using radio

buttons for payment options:

Express Checkout Integration Guide August 7, 2012 33

Getting Started With Express Checkout

Express Checkout Building Blocks

Express Checkout API Operations

The PayPal API provides three API operations for Express Checkout. These API operations

set up the transaction, obtain information about the buyer, and handle the payment and

completes the transaction.

Express Checkout Command

PayPal provides a command that you use when redirecting your buyer’s browser to PayPal.

This command enables your buyer to log in to PayPal to approve an Express Checkout

payment.

When you redirect your buyer’s browser to PayPal, you must specify the

_ExpressCheckout command for Express Checkout. You also specify the token that

identifies the transaction, which was returned by the SetExpressCheckout API operation.

NOTE:To enable PayPal to redirect back to your website, you must have already invoked the

SetExpressCheckout API operation, specifying URLs that PayPal uses to redirect

back to your site. PayPal redirects to the success URL when the buyer pays on PayPal;

otherwise, PayPal redirects to the cancel URL.

If the buyer approves the payment, PayPal redirects to the success URL with the following

information:

-The token that was included in the redirect to PayPal

-The buyer’s unique identifier (Payer ID)

If the buyer cancels, PayPal redirects to the cancel URL with the token that was included in the

redirect to PayPal.

API Operation Description

SetExpressCheckout Sets up the Express Checkout transaction. You can specify information

to customize the look and feel of the PayPal site and the information it

displays. You must include the following information:

-URL to the page on your website that PayPal redirects to after the

buyer logs into PayPal and approves the payment successfully.

-URL to the page on your website that PayPal redirects to if the buyer

cancels.

-Total amount of the order or your best estimate of the total. It should

be as accurate as possible.

GetExpressCheckout Obtains information about the buyer from PayPal, including shipping

information.

DoExpressCheckoutPayment Completes the Express Checkout transaction, including the actual total

amount of the order.

Getting Started With Express Checkout

Express Checkout Building Blocks

34 August 7, 2012 Express Checkout Integration Guide

Express Checkout Token Usage

Express Checkout uses a token to control access to PayPal and execute Express Checkout API

operations.

The SetExpressCheckout API operation returns a token, which is used by other Express

Checkout API operations and by the _ExpressCheckout command to identify the

transaction. The life of the token is approximately 3 hours.

Express Checkout Integration Guide August 7, 2012 35

2Express Checkout User Interface

Requirements

Your Express Checkout integration must conform to PayPal’s requirements for button use and

placement. You must use only buttons hosted on PayPal and place them on your checkout and

payment pages.

Express Checkout Flow

To implement Express Checkout, you must offer it both as a checkout option and as a payment

method. Typically, you initiate the Express Checkout flow on your shopping cart page and on

your payment options page.

You add Express Checkout to your existing flow by placing the Checkout with PayPal button

on your Shopping Cart page and by placing the PayPal mark on your Payment Methods

page. The following diagram shows the complete flow:

Complete Express Checkout flow

Make the following changes to implement the complete Express Checkout flow:

-On your Shopping Cart page, place the Checkout with PayPal button. Handle clicks by

sending the Express Checkout setup request. After receiving the response, redirect your

buyer’s browser to PayPal.

-On your Payment Methods page, associate the PayPal mark with an option. Handle clicks

by sending the Express Checkout setup request. After receiving the response, redirect your

buyer’s browser to PayPal.

-On the page your buyer returns to, obtain shipping information from PayPal and accept the

payment to complete the Express Checkout transaction.

Express Checkout User Interface Requirements

Express Checkout Flow

36 August 7, 2012 Express Checkout Integration Guide

NOTE:You also can allow the buyer to pay on the PayPal Review page. In this case, your

checkout flow can omit the Merchant Review page and proceed directly to your

Confirmation page.

Related information:

"Implementing the Simplest Express Checkout Integration" on page 13

Checkout Entry Point

The checkout entry point is one of the places where you must implement Express Checkout.

Buyers initiate the Express Checkout flow on your shopping cart page by clicking the

Checkout with PayPal button.

The following diagram shows how Express Checkout integrates with a typical checkout flow:

Payment Option Entry Point

The payment option entry point is one of the places where you must implement Express

Checkout. Buyers initiate the Express Checkout flow on your payment methods page by

selecting PayPal as the default option.

The following diagram shows how to integrate Express Checkout from your payment methods

page:

Express Checkout Integration Guide August 7, 2012 37

Express Checkout User Interface Requirements

PayPal Button and Logo Images

To inform buyers that PayPal is accepted on your website, you must place PayPal button and

logo images in your checkout flow. PayPal recommends that you use dynamic images.

PayPal requires that you use Check out with PayPal buttons and PayPal mark images hosted

on secure PayPal servers. When the images are updated, the changes appear automatically in

your application. Do not host copies of the PayPal images locally on your servers. Outdated

PayPal buttons and images reduce buyer confidence in your site.

Express Checkout Image Flavors

The Check out with PayPal button and the PayPal mark image are available in two flavors:

-Dynamic image

-Static image

The dynamic images enable PayPal to change their appearance dynamically. If, for example,

you have signed up to participate in a PayPal campaign, PayPal can change the appearance of

the image dynamically for the duration of that campaign based on parameter information you

append to the image URL.

The static images cannot be changed dynamically. To participate in a PayPal campaign, you

would have to manually update the image code to change the image displayed and restore the

default image when the campaign is over. The only way you can have image management

taken care of for you is to replace static images in your implementation with dynamic images.

Express Checkout Images

The Check out with PayPal button is the image you place on your shopping cart page. The

US version of the image looks like this.

Express Checkout User Interface Requirements

PayPal Button and Logo Images

38 August 7, 2012 Express Checkout Integration Guide

To create an Express Checkout button, see https://www.paypal.com/us/cgi-

bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal also

provides buttons for other countries. To locate a page for another country, replace the country

abbreviation in the link with another country abbreviation. For example, replace us with uk

for United Kingdom, as follows: https://www.paypal.com/uk/cgi-

bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal hosts images

for the countries:

Country-specific buttons and images

NOTE:URL changes are case sensitive. The abbreviation in the URL may not be a country

code.

Payment Mark

The PayPal mark is the image you place on your payment methods page. It looks like this:

To implement PayPal as a payment option, which is part of the Express Checkout experience,

associate the PayPal mark image with your payment options. PayPal recommends using radio

buttons for payment options:

To create a PayPal mark, see https://www.paypal.com/cgi-

bin/webscr?cmd=xpt/Marketing/general/OnlineLogoCenter-outside.

Country URL

Change Country URL

Change

Australia au Austria at Belgium be Canada ca

China cn France fr Germany de Italy it

Japan j1 Netherlands nl Poland pl Spain es

Switzerland ch United

Kingdom uk United

States us

Express Checkout Integration Guide August 7, 2012 39

3Related API Operations

When you create the simplest Express Checkout integration, you specify Sale as the payment

action, enabling you to receive the money right away. You can also set up a payment to be

collected later, or refund a payment.

Sale Payment Action for Express Checkout

A sale payment action represents a single payment that completes a purchase for a specified

amount.

A sale is the default Express Checkout payment action; however, you can also specify the

following action in your SetExpressCheckout and DoExpressCheckoutPayment

requests:

PAYMENTREQUEST_n_PAYMENTACTION=Sale

A sale is the most straightforward payment action. Choose this payment action if the

transaction, including shipping of goods, can be completed immediately. To use this payment

action:

-The final amount of the payment must be known when you invoke the

DoExpressCheckoutPayment API operation

-You should intend to fulfill the order immediately, such as would be the case for digital

goods or for items you have in stock for immediate shipment

After you execute the DoExpressCheckoutPayment API operation, the payment is

complete and further action is unnecessary. You cannot capture a further payment or void any

part of the payment when you use this payment action.

Authorization Payment Action for Express Checkout

An authorization payment action represents an agreement to pay and places the buyer’s funds

on hold for up to three days.

To set up an authorization, specify the following payment action in your

SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTREQUEST_n_PAYMENTACTION=Authorization

Related API Operations

Order Payment Action for Express Checkout

40 August 7, 2012 Express Checkout Integration Guide

An authorization enables you to capture multiple payments up to 115% of, or USD $75 more

than, the amount you specify in the DoExpressCheckoutPayment request. Choose this

payment action if you need to ship the goods before capturing the payment or if there is some

reason not to accept the payment immediately.

The honor period, for which funds can be held, is three days. The valid period, for which the

authorization is valid, is 29 days. You can reauthorize the 3-day honor period at most once

within the 29-day valid period.

You can void an authorization, in which case the uncaptured part of the amount specified in

the DoExpressCheckoutPayment request becomes void and can no longer be captured. If

no part of the payment has been captured, the entire payment becomes void and nothing can be

captured.

API operations associated with Authorization payment action in Express Checkout

Order Payment Action for Express Checkout

An order payment action represents an agreement to pay one or more authorized amounts up

to the specified total over a maximum of 29 days.

To set up an order, specify the following payment action in your SetExpressCheckout and

DoExpressCheckoutPayment requests:

PAYMENTREQUEST_n_PAYMENTACTION=Order

An order enables you to create multiple authorizations over the 29 days; each authorization

you create places the buyer’s funds on hold for up to three days. You can capture multiple

payments for each authorization, up to 115% of, or USD $75 more than, the amount you

specify in the DoExpressCheckoutPayment request.

NOTE:The default number of child authorizations in your PayPal account is 1. To do

multiple authorizations please contact PayPal to request an increase.

This payment action provides the most flexibility and should be used when either a sale does

not meet, or one authorization plus one reauthorization, do not meet your needs. Situations in

which orders are appropriate include the handling of:

-Back orders, in which available merchandise is sent immediately and the remaining

merchandise is sent when available, which may include more than two shipments

-Split orders, in which merchandise is sent in more than one shipment, perhaps to different

addresses, and you want to collect a payment for each shipment

API Operation Description

DoCapture Capture an authorized payment.

DoReauthorization Reauthorize a payment.

DoVoid Void an order or an authorization.

Express Checkout Integration Guide August 7, 2012 41

Related API Operations

Issuing Refunds

-Drop shipments, which are shipments from other vendors for which you accept the

payment

You cannot reauthorize an authorization. You handle the need to reauthorize, for example

when the hold period or valid period of an authorization expires, simply by creating another

authorization.

You can void an order or an authorization created from the order. If you void an order, the

uncaptured part of the amount specified in the DoExpressCheckoutPayment request

becomes void and can no longer be captured. If no part of the payment has been captured, the

entire payment becomes void and nothing can be captured.

If you void an authorization associated with the order, the uncaptured part of the amount

specified in the authorization becomes void and can no longer be captured. If no part of the

authorization has been captured, the entire authorized payment becomes void.

API operations associated with Order payment action in Express Checkout

Issuing Refunds

You can use the RefundTransaction PayPal API operation to issue refunds.

Use the RefundTransaction API to issue one or more refunds associated with a

transaction, such as a transaction created by a capture of a payment. The transaction is

identified by a transaction ID that PayPal assigns when the payment is captured.

NOTE:You cannot make a refund if the transaction occurred after the refund period has

passed; typically, the refund period is 60 days.

You can refund amounts up to the total amount of the original transaction. If you specify a full

refund, the entire amount is refunded. If you specify a partial refund, you must specify the

amount to refund, the currency, and a description of the refund, which is called a memo.

When you call the RefundTransaction API, PayPal responds with another transaction ID,

which is associated with the refund (not the original transaction), and additional information

about the refund. This information identifies:

-The gross amount of the refund, which is returned to the payer

-The amount of the refund associated with the original transaction fee, which is returned to

you

-The net amount of the refund, which is deducted from your balance

To issue a refund:

API Operation Description

DoAuthorization Authorize a payment.

DoCapture Capture an authorized payment.

DoVoid Void an order or an authorization.

Related API Operations

Tracking Failed or Pending Requests

42 August 7, 2012 Express Checkout Integration Guide

1. In the RefundTransaction request, specify the transaction ID of the transaction whose

payment you want to refund.

TRANSACTIONID=transaction_id

2. Specify the kind of refund, which is either Full or Partial.

REFUNDTYPE=Full

REFUNDTYPE=Partial

3. For a partial refund, specify the refund amount, including the currency.

AMT=amount

CURRENCYCODE=currencyID

4. For a partial refund, specify the memo description.

NOTE=description

5. Execute the RefundTransaction operation.

6. Check the acknowledgement status in the RefundTransaction response to ensure that

the operation was successful.

Related information:

"Refunds" on page 28

Tracking Failed or Pending Requests

You can use the MsgSubID (Message Submission ID) to help track pending or failed requests.

MsgSubID has been added to the request and response for following API calls:

-DoAuthorization

-DoReferenceTransaction

-RefundTransaction

-DoCapture

Idempotency is useful in cases where a request has failed or if you are unsure about the results

of an original request. It also helps to correlate request payloads with response payloads.

Idempotency helps to eliminate duplicate requests, since a request sent with a previously

accompanying MsgSubID will return with latest status of of the previous request that used the

Express Checkout Integration Guide August 7, 2012 43

Related API Operations

Tracking Failed or Pending Requests

same MsgSubID. In contrast, a request with no accompanying MsgSubID will instead

duplicate the request.

Scenarios in which idempotency come into play:

-In an API request sent with a MsgSubID times out, a client application can retry the

original request using the accompanying MsgSubID. If the request has finished processing,

PayPal then provides the latest status of the request and might return a 11607 warning

code (Duplicate request for specified Message Submission ID).

-If a client application sends two API requests with same MsgSubID at the same time,

PayPal processes the first request and the other may fail with 11604 error code (Request

for Message Submission ID already in progress).

NOTE:For DoExpressCheckoutPayment, you can use the token in place of the

MsgSubID. For mutliple payments, a combination of the token and

PaymentRequestID should be used in place of the MsgSubID.

The following example shows MsgSubID used as part of a DoAuthorization request:

<__value__>

<m__value>Order</m__value>

</__value__>

</transactionEntity>

<__value>10</__value>

<__value__>

<m__value>USD</m__value>

</__value__>

</currencyID>

</amount>

Usage Notes:

-The MsgSubID must be unique for each request and, as a best practice, should be unique to

an API call type (e.g. DoAuthorization, DoCapture).

-PayPal recommends using the UUID standard for assigning a MsgSubID to your request,

since it meets the 38 single-byte character limit for MsgSubID.

-Idempotency only applies when the original request was successful. If the original request

results in an error, the original request is not saved.

-PayPal reserves the right to expire a MsgSubID after 13 days.

-PayPal provides the status of a request at the current time and not the status of the initial

request. Take for example, an initial request that makes a payment (status is Complete).

The payment is later refunded. If the original request with the original MsgSubId is

resubmitted, the response will indicate that the payment status is Refunded.

Related API Operations

Tracking Failed or Pending Requests

44 August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 45

4Integrating Express Checkout

With PayPal SDKs

You can choose to use a PayPal SDK instead of creating messages as NVP strings or SOAP

structures. These SDKs enable you to code in your preferred programming language, such as

Java, PHP, Ruby, and more.

In addition to working in the programming language of your choice, SDKs make it easy to

perform common tasks, such as encoding and decoding of messages and managing

credentials. For more information about SDKs and to download the preferred one for your

environment, see:

-PayPal API: Name-Value Pair Interface

-PayPal API: SOAP Interface

Integrating Express Checkout With PayPal SDKs

46 August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 47

5Going Live With Your Express

Checkout Integration

After your application works with the PayPal Sandbox, and you are ready to move it into live

production, review the checklist to make sure you are not forgetting any steps for going live.

1. Create and configure your live PayPal account.

NOTE:If you are executing Express Checkout or other PayPal API operations on behalf of

another merchant, you must obtain permission to execute them in production. In

other words, the merchant for whom you execute API operations must grant

permission to you so that you can perform the operation in production.

2. Verify that your live account’s profile settings match those in your sandbox account’s

profile or that you understand and approve the differences.

3. Set up credentials for your live PayPal account.

API credentials are associated with an account; thus, your credentials in production are

different than those for the sandbox. You must obtain either a different signature or

download a different certificate for your live account.

4. If your application uses a PayPal SDK, create an API Profile object that contains the

details of your live account.

You must specify the environment field as live and, if you use a certificate, include the

API username, API password, and path to your production API certificate associated with

your live account.

5. Add PayPal's IP addresses to any list of trusted IP addresses needed by your firewall or

other network devices. See the GoLive Checklist for more information:

https://cms.paypal.com/us/cgi-bin/?cmd=_render-

content&content_ID=developer/howto_api_golivechecklist

Going Live With Your Express Checkout Integration

48 August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 49

AObtaining API Credentials

To use the PayPal API, you must have API credentials that identify you as a PayPal Business

or Premier account holder who is authorized to perform various API operations. Although you

can use either an API signature or a certificate for credentials, PayPal recommends you use a

signature.

IMPORTANT:Although you can have both a signature and certificate, you cannot use both at

the same time.

Creating an API Signature

An API signature consists of an API username along with an associated API password and

signature, all of which are assigned by PayPal. You need to include this information whenever

you execute a PayPal API operation.

You must have a PayPal Business account to create a signature.

To create an API signature:

1. Log in to PayPal, then click Profile under My Account.

2. Click My selling tools.

3. Click API Access.

4. Click Request API Credentials.

5. Check Request API signature and click Agree and Submit.

Obtaining API Credentials

Creating an API Certificate

50 August 7, 2012 Express Checkout Integration Guide

6. Click Done to complete the process.

Creating an API Certificate

Create an API certificate only if your website requires it. Typically, you want to create an API

signature for your credentials instead.

You must have a PayPal Business account to create an API certificate.

NOTE:The certificate for API credentials is not the same as an SSL certificate for your

website; they are not related to each other.

If you do need a certificate, follow these instructions:

1. Log in to PayPal, then click Profile under My Account.

2. Click My selling tools.

3. Click API Access.

4. Click Request API Credentials.

5. Check Request API certificate and click Agree and Submit.

Express Checkout Integration Guide August 7, 2012 51

Obtaining API Credentials

Creating an API Certificate

6. Save the values for API Username and API Password for later use.

7. Click Download Certificate and save the file.

8. Rename this file to something familiar, such as paypal_live_cert.pem.

It is not necessary to keep the .txt file extension. Be sure to remember where you save the

file.

After Completing This Task:

-If you use the PayPal SDK for Java, the PayPal SDK for .NET, or the PayPal SDK for

Classic ASP, you must encrypt your certificate in PCKS12 format.

-If you use the PayPal SDK for .NET or Classic ASP, you must take additional steps to

import the certificate.

Encrypting Your Certificate Into PKCS12 Format

PayPal SDKs for Java, .NET, and Classic ASP require the additional task of encrypting your

certificate into PKCS12 format. Perform this task for both your Sandbox certificate and your

live certificate.

NOTE:This task is not required if you are using the PayPal SDK for PHP.

The certificate you download from PayPal is in PEM format. It contains both your public

certificate and the associated private key. Although the PEM certificate is not human readable,

the file is not encrypted.

Obtaining API Credentials

Creating an API Certificate

52 August 7, 2012 Express Checkout Integration Guide

The steps in this task require you to use the OpenSSL encryption tool. On Unix, this tool is

typically installed for you. On Windows, you typically must download OpenSSL yourself; in

this case, accept the defaults when you install OpenSSL and add OpenSSL to the path.

NOTE:In Windows, the Path is a System environment variable, which is accessible from the

Advanced tab when you right-click on your My Computer icon and view its

properties. Do not confuse the System variables path with with the User variables

path. Add OpenSSL to the System variables path.

To encrypt your certificate into PKCS12 format:

1. Use OpenSSL to create the PKCS12-format certificate from the downloaded PEM-format

certificate.

openssl pkcs12 -export -in download.txt -inkey download.txt -out

certificate.p12

2. At the prompt, enter an Export Password for the certificate.

3. Save your Export Password.

Importing Your Certificate

For either PayPal SDK for .NET or Classic ASP, you must download and execute the

Windows HTTP Services Certificate Configuration Tool, WinHTTPCertCfg. If you use the

.NET platform and develop with the PayPal SDK for .NET, you need to take a few more steps

before your certificate can be used.

You must use WinHTTPCertCfg to import the certificate into the Windows Certificate Store

and grant access to your private key to the user executing your web application. This is a

Windows requirement, not a PayPal requirement. You can download WinHTTPCertCfg from

the Microsoft Windows Server 2003 Resource Kit Tools page

(http://www.microsoft.com/downloads/en/details.aspx?familyid=9d467a6

9-57ff-4ae7-96ee-b18c4790cffd&displaylang=en). For Microsoft documentation,

see WinHttpCertCfg.exe, a Certificate Configuration Tool.

To import a certificate:

1. Execute WinHTTPCertCfg to import the certificate into the Windows Certificate Store

and grant access to your private key to the party executing your web application.

WinHttpCertCfg -i certificate.p12 -p privateKeyPassword -c

where certificate is your PKCS12 certificate and privateKeyPassword is your Export

Password.

Express Checkout Integration Guide August 7, 2012 53

Obtaining API Credentials

Creating an API Certificate

2. Using WinHTTPCertCfg, change the username in LOCAL_MACHINE\My -a username

to one of the following values:

Configuration Username value

ASP. NET ASPNET

Windows IIS 5 default configuration IWAM_machineName, where machineName is the computer

name

Windows IIS 6 default configuration “NETWORK SERVICE” (You must include the quote marks.)

Obtaining API Credentials

Creating an API Certificate

54 August 7, 2012 Express Checkout Integration Guide

Express Checkout Integration Guide August 7, 2012 55

BPayPal Name-Value Pair API

Basics

The Name-Value Pair (NVP) API provides parameter-based association between request and

response fields of a message and their values. The request message is sent from your website

by the API, and a response message is returned by PayPal using a client-server model in which

your site is a client of the PayPal server.

NOTE:The PayFlow API also uses name-value pairs to provide parameter-based association

between request and response fields of a message and their values; however, the

PayFlow API is not the same as the NVP API; for more information about the

PayFlow API, see Gateway Developer Guide and Reference.