NVP/SOAP Express Checkout

This page contains reference information for Express Checkout integrations that use the NVP/SOAP API.

Overview

These sections provide a high-level overview of NVP/SOAP Express Checkout:

Checkout flow

Before you implement NVP/SOAP Express Checkout, consider a buyer's checkout flow. A generic flow typically follows this sequence:

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 NVP/SOAP Express Checkout flow, the buyer does not enter shipping, billing, or payment information, because PayPal provides the stored information. This simplifies and expedites the checkout process.

This diagram shows the simplified flow:

In the NVP/SOAP Express Checkout flow, the buyer:

  1. Clicks Buy Now
  2. Logs into PayPal to authenticate his or her identity
  3. Reviews the transaction on PayPal
  4. Confirms the order and pays from your site
  5. Receives an order confirmation

Supported countries and currencies

NVP/SOAP Express Checkout enables you to accept payments from many countries and regions. The checkout flow is also localized for a subset of countries. For more information, see PayPal Offerings Worldwide and visit your country-specific site for further details.

When issuing API operations, refer to currency codes and country codes.

Shopping carts

If your site does not have a shopping cart and you have not yet integrated with NVP/SOAP Express Checkout, consider using a third-party shopping cart. A shopping cart lets buyers put items in a basket and calculates totals during checkout.

PayPal partners with a wide variety of shopping cart companies, 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: PayPal has no authority over third-party shopping cart vendors and cannot help you resolve issues that might arise from the integration with or use of a third-party shopping cart.

Prerequisites

Prerequisites to use the NVP/SOAP Express Checkout include:

  • A Business or Premier account

    These account types enable 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 PayPal Sandbox account

    The sandbox environment simulates the live PayPal environment, where you can execute transactions without actually exchanging money. When you create a sandbox account, you automatically get a seller account and a buyer account.

  • HTML coding experience

    Using HTML, you add a payment button and a PayPal mark to your web page. The payment button initiates the checkout flow. If the buyer did not start the checkout flow using a payment button, the mark enables the buyer to choose PayPal from the payment method page.

  • Programming experience

    You must provide code that requests a PayPal server to set up or process the transaction when a buyer clicks a payment button, and code to handle the server's response. To create the code, PayPal offers several different tools:

    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 you do not have programming experience, consider using PayPal Payments Standard or a shopping cart provided by a PayPal Partner.

For integration assistance, contact Merchant Technical Support.

Before you start coding

If you are unfamiliar with PayPal APIs, see the PayPal Name-Value Pair API page, which provides the minimum information you need to be successful.

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. This diagram shows the basic request-response mechanism.

For example, you want to obtain the buyer's shipping address from PayPal. You initiate a request specifying an API operation to obtain buyer details. If successful, the server's response contains the buyer's shipping address. If the operation fails, the response contains one or more error messages.

Creating the checkout flow

To implement the checkout flow, you use payment buttons, PayPal NVP/SOAP API operations, and Express Checkout commands and tokens.

This diagram shows the payment button and API operations:

In certain cases, you may also use a second redirect flow.

Payment buttons and mark images

PayPal requires that you use payment button and mark images that are hosted on secure PayPal servers. When the images are updated, the changes appear automatically in your application.

Place the payment button on your checkout page and the PayPal mark on your payment options page. To obtain an HTML button and PayPal mark, see PayPal buttons, logos, and marks.

NVP/SOAP API operations

The NVP/SOAP 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 transaction, including the actual total amount of the order.

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 the payment.

When you redirect your buyer's browser to PayPal, you must specify the _ExpressCheckout command . 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 specify the redirect URLs have in the SetExpressCheckout API operation. 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)

Note: When redirecting the buyer back to your website from paypal.com, PayPal appends the Express Checkout transaction token and the unique PayPal buyer ID as GET parameters to your RETURN URL; these GET parameters are named token and PayerID.

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

In some cases, merchants may need to redirect the buyer back to PayPal a second time. For more information, see Second redirect flow.

Tokens

The SetExpressCheckout API call returns a token, which identifies and track the transaction. You use the token with subsequent API and the _ExpressCheckout command. The life of the token is approximately 3 hours.

Second redirect flow

If a funding failure occurs, you can redirect the buyer back to PayPal a second time so the he or she can select or add a different funding source. For more information on funding failures, see Error Handling.

When you call SetExpressCheckout, the response contains a new token. You then redirect the buyer to the checkout flow, where the buyer logs in (or signs-up in the case of buyers new to PayPal). At the end of the flow, PayPal redirects the buyer to your purchase confirmation page.

If a buyer makes significant changes to their shopping cart after being redirected to your site from PayPal, you can use the second redirect flow to update the buyer's cart information. In this instance, you pass the same token returned from the first SetExpressCheckout call, so the buyer is not required to sign in to PayPal again.

To implement this flow, call SetExpressCheckout (NVP | SOAP) again with the updated transaction information and provide the same token you received from the first SetExpressCheckout call response.

This diagram illustrates the second redirect flow:

  1. After you call SetExpressCheckout a second time using the same token returned from the first SetExpressCheckout call, PayPal updates the cart information. The buyer is not required to log in to PayPal on the second redirect.

  2. Once the buyer accepts the updated payment amount, PayPal redirects the buyer back to your purchase confirmation page.

Troubleshooting

This section provides troubleshooting tips for NVP/SOAP Express Checkout integrations. If you are unable to resolve an issue, gather some basic information, including a log of the actions that led to the error, and contact Merchant Technical Support (MTS).

Error handling

Response messages contains an ACK value. A successful returns returns ACK=Success If ACK returns any other value, 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 NVP/SOAP Express Checkout error codes, see 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 problems can indicate risk, do not ship goods until the buyer resolves the issue. 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. For information about how to redirect buyers to PayPal when the 10486 error occurs, see How To Recover from Funding Failure 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. To prevent problems, thoroughly test your integration in the the Sandbox before your site goes 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. Do not ship goods before you receive a valid transaction ID that indicates that PayPal accepted the payment.

It is safe to execute the API operation again if the status is unknown. 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 call 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 time stamp, 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.

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.

Features

This section describes features and tools for NVP/SOAP Express Checkout.

Payment types

You can collect a payment immediately or capture it later when you ship the the purchased goods. When you create a payment, you specify the transaction details and the payment type. You can use these payments types:

  • sale to accept a payment and ship goods immediately.

  • authorization to reserve a buyer's funds before you ship goods. For example, you might re-authorize a payment when you cannot ship goods within the three-day honor period of the original authorization period.

  • order when a single authorization is not sufficient. You can create multiple authorizations and capture them as part of the same order. Use an order to split payments across multiple shipments.

For more information, see Express Checkout related API operations.

Refunds

You can issue a full or partial refund for up to the full amount of the payment. You can make a refund for payments captured initially or as part of a later settlement.

If a transaction occurred after the default refund period of 180 days, you cannot use the RefundTransaction API operation to issue the refund. For more information, see the RefundTransaction (NVP | SOAP) API Operation.

Setting up payments

You can these implement these payment features using NVP/SOAP API operations:

Customizing the checkout page

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

Express Checkout includes these checkout page options:

  • Display your company logo
  • Display a specific language

Note: You can set these customizations 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.

For the PayPal shopping cart pull-down menu, 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
  • Assign an invoice number to a payment

There are several options for displaying the shipping address, including shipping to a confirmed address, suppressing the address, and overriding the shipping address.

For more information, see Customizing Express Checkout.

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 (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. 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 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, direct credit card payments and authorizations (transaction payments that are authorized but have 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
  • Charge-backs, disputes, reversals, and refunds associated with a transaction

For more information about IPN, see the Instant Payment Notification Guide