Getting Started With 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.


Contents

Introduction

Relationship Between Express Checkout and Shopping Carts

Express Checkout Prerequisites

Express Checkout Building Blocks

Express Checkout Command

Implementing the Simplest Express Checkout Integration

Troubleshooting Your Express Checkout Integration

Express Checkout Features


Introduction

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. The following web page shows the Express Checkout button side-by-side with an existing checkout button.

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.
  • See more at: https://www.paypal.com/webapps/mpp/express-checkout

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:

Figure 1. 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:

Figure 2. 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
  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 Confirm 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 and visit your country-specific site for further details.

Also, you may want to bookmark the reference pages for currency codes and country codes used in the API operations.

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 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 a PayPal Partner.

To use Express Checkout, you must have:

  • A Business or Premier PayPal 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 coding 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 Name-Value Pair interface built on the HTTP request-response model, as well as a more complicated SOAP web services interface. Additionally, PayPal provides an Integration Wizard. You can also choose to use a Software Development Kit (SDK) that provides 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.

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:

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:

These are explained below in the Obtaining an Express Checkout Button and PayPal Mark.

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.

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.

These API operations are explained in further detail below in implementing the Simplest Express Checkout Integration.

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.

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.

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.

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.

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

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:

For more information, see Express Checkout user interface requirements.

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.

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.

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. See Creating and Managing Classic API Credentials for details.

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 (NVP | SOAP) 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:

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

    METHOD=SetExpressCheckout
    VERSION=109.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 should not exceed any per transaction amount limits for the currency used.

    	PAYMENTREQUEST_0_AMT=amount
    	PAYMENTREQUEST_0_CURRENCYCODE=currencyID
    
  4. Specify the return URL. The return URL is the page on your website to which PayPal redirects yourbuyer'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
    
  5. Specify the cancel URL.

    The cancel URL is the page on your website 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 cancel URL to have the values available, if necessary, after PayPal redirects to your cancel 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 Sale, Authorization or Order. See Related API Operations for details.

    PAYMENTREQUEST_0_PAYMENTACTION=Sale
    

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/cgi-bin/webscr?cmd=_express-checkout&token=tokenValue

Obtaining Express Checkout Transaction Details

To obtain details about an Express Checkout transaction, you can invoke the GetExpressCheckoutDetails (NVP | SOAP) 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 from this API operation:

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

    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 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 (NVP | SOAP) 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 in the DoExpressCheckoutPayment call 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 API version you want to use.
    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 the default currency, 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, a testing environment provided by PayPal.

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. 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:

    	<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
    		<input type=hidden name=USER value=API_username>
    		<input type=hidden name=PWD value=API_password>
    		<input type=hidden name=SIGNATURE value=API_signature>
    		<input type=hidden name=VERSION value=XX.0>
    		<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
    			value=Sale>
    		<input name=PAYMENTREQUEST_0_AMT value=19.95>
    		<input type=hidden name=RETURNURL
    			value=https://www.YourReturnURL.com>
    		<input type=hidden name=CANCELURL
    			value=https://www.YourCancelURL.com>
    		<input type=submit name=METHOD value=SetExpressCheckout>
    	</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.

    Tip

    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 log in, as follows:

    	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
    		<input type=hidden name=USER value=API_username>
    		<input type=hidden name=PWD value=API_password>
    		<input type=hidden name=SIGNATURE value=API_signature>
    		<input type=hidden name=VERSION value=XX.0>
    		<input name=TOKEN value=EC-1NK66318YB717835M>
    		<input type=submit name=METHOD value=GetExpressCheckoutDetails>
    	</form>
    

    If the operation was successful, the GetExpressCheckoutDetails API returns information about the payer, such as the following information:

    	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:

    	<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
    		<input type=hidden name=USER value=API_username>
    		<input type=hidden name=PWD value=API_password>
    		<input type=hidden name=SIGNATURE value=API_signature>
    		<input type=hidden name=VERSION value=XX.0>
    		<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
    			value=Sale>
    		<input type=hidden name=PAYERID value=7AKUSARZ7SAT8>
    		<input type=hidden name=TOKEN value= EC%2d1NK66318YB717835M>
    		<input type=hidden name=PAYMENTREQUEST_0_AMT value= 19.95>
    		<input type=submit name=METHOD value=DoExpressCheckoutPayment>
    	</form>
    
  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.

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. NVP 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. The equivalent SOAP error fields are: ErrorCode, ShortMessage and LongMessage.

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.

For a list of ExpressCheckout error codes grouped by API call, refer to the Merchant API error codes.

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. Because these kinds of problems can indicate a risk issue, you do not want to ship goods until the issue has been resolved. 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. This HowTo Guide provides some information on redirecting buyers back to PayPal after PayPal returns error code 10486.

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.

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 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
  • Gradient fill color of the border around the cart review area
  • Language in which PayPal content is displayed
  • Your customer service number

Note All of the above customizations can be set in the profile settings of your paypal account. 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

See Customizing Express Checkout for more information.

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.

See Express Checkout related API operations for more information.

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.

You cannot make a refund using the RefundTransaction API operation if the transaction occurred after the refund period has passed, which typically is 60 days. See the RefundTransaction (NVP | SOAP) API Operation for more information.

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 schedule variable payment amounts 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.

See Express Checkout reference transactions for more information.

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.

See Express Checkout on mobile devices for more information.

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.

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.

See Express Checkout Parallel Payments for more information.

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 PayPal Payments Pro (previously known as Website Payments Pro) accounts.
  • Advanced filters screen data such as credit card and addresses information, lists of high-risk indicators, and additional transaction characteristics. PayPal 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 the Fraud Management Filters integration guide.

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 Instant Payment Notifications (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 the Instant Payment Notification Guide

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.

See Express Checkout dynamic image integration for more information.

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.

The Instant Update API is a server call to your callback server that instantly updates PayPal pages and enhances the Express Checkout experience on the Review your information page.

The Instant Update API enables you to specify a URL with which PayPal can call your callback server with the buyer's shipping address, so you can provide the buyer with more detailed shipping, insurance, and tax information.

See the Implementing the Instant Update API for more information.

Merchant Coupons and Loyalty Program Support

Starting in v113 of the API, Express Checkout will support merchant coupons and loyalty programs.

See How To Use Coupons and Loyalty Programs in Express Checkout for more information.

User Interface Requirements >>