Express Checkout API Getting Started Guide

This service helps you streamline the checkout process for a buyer. The payment experience is on paypal.com (a redirection from the merchant's site) and then the buyer is returned to the merchant's site for payment confirmation. To use this service, the merchant must have a PayPal merchant account.

You can see a demo of Express Checkout on the Demo Portal .

Key Concepts

The key participants in Express Checkout are the person making a payment (payer), the person receiving the funds (payee), and the application that is calling Express Checkout. You can add buttons on the checkout and payment method web pages to call the Express Checkout API. These enable PayPal users to bypass pages about shipping and about the payment method.

Typical Checkout Flow

The typical checkout flow, without Express Checkout, is the following:

Select checkout Provide shipping info Select payment method
    Review summary for approval See confirmation of transaction

In contrast, you can use Express Checkout to create an easier, faster checkout flow. For example, here is a common Express Checkout flow:

The following steps describe one of the call flows in Express Checkout. For how to use all four steps, see How to Create One-Time Payments Using Express Checkout.

  1. Call SetExpressCheckout to set up the transaction and define the URL to which the customer is returned after the customer authorizes payment.
  2. Redirect the customer to PayPal for authorization of the payment.
  3. Call GetExpressCheckoutDetails to obtain customer information, e.g. for customer review before payment.
  4. Call DoExpressCheckoutPayment to complete the transaction.

You can make calls in these formats:

Request method, format Response format
HTTP GET Name/value pairs JSON
HTTP POST SOAP (1.1, 1.2) SOAP

There are calls you can make to handle exceptions, e.g. you can void a transaction when a buyer cancels out of checkout.

Making Your First Call

The following example calls SetExpressCheckout in the Sandbox with the specified app (signified by combination of USER, PWD, and SIGNATURE) to initiate a $10 payment.

  1. Obtain the endpoint for the service and environment you are addressing.
    https://api-3t.sandbox.paypal.com/nvp
    

    This is the endpoint for making calls in name/value pair style in the Sandbox. For the SOAP endpoint, see API endpoints.

  2. Provide the authentication, as shown in the SetExpressCheckout call below:
    // Sandbox API credentials for the API caller account
    USER : // user id
    PWD : // password
    SIGNATURE : // signature
    VERSION : // the release version of the API
    
  3. Provide parameters needed by the specific call being made (for this example, see SetExpressCheckout).
    METHOD : SetExpressCheckout
    PAYMENTREQUEST_0_AMT : // payment amount
    PAYMENTREQUEST_0_PAYMENTACTION : // type of transaction
    PAYMENTREQUEST_0_CURRENCYCODE : // payment currency code
    returnUrl : // redirect URL for use if the customer authorizes payment
    cancelUrl : // redirect URL for use if the customer does not authorize payment
    
  4. Make the call. (For an example, see Try It below.)
  5. Evaluate the response.

    If you run the Try It example below, the response could be similar to the following (which has been split to multiple lines for readability):

    ACK=Success
    // a reference to the payment transaction that can be processed on paypal.com
    &TOKEN=EC%2d5T410414TT256914A
    // additional data about the API call
    &TIMESTAMP=2011%2d08%2d09T18%3a21%3a32Z&CORRELATIONID=29bfef7d4d383&VERSION=78&BUILD=2020243LM-SJN-00711105:
    

    (If the call fails with an ACK value of Failure, consider the details in the error message. )

Try it!

This example shows a SetExpressCheckout Sandbox call that initiates a $10 payment. The combination of the USER, PWD, and SIGNATURE values identifies the app that makes the API call.

  1. Copy this cURL command:
    curl -s --insecure  https://api-3t.sandbox.paypal.com/nvp  -d  "USER=platfo_1255077030_biz_api1.gmail.com&PWD=1255077037&SIGNATURE=Abg0gYcQyxQvnf2HDJkKtA-p6pqhA1k-KTYE0Gcy1diujFio4io5Vqjf&METHOD=SetExpressCheckout&VERSION=78&PAYMENTREQUEST_0_PAYMENTACTION=SALE&PAYMENTREQUEST_0_AMT=19&PAYMENTREQUEST_0_CURRENCYCODE=USD&cancelUrl=http://www.example.com/cancel.html&returnUrl=http://www.example.com/success.html"
    
  2. Run the cURL command. (If the curl command is not found on your computer, download the free cURL executable.)

Next Steps

Using the Sandbox Environment

To make test calls, you need a Sandbox account, test users, and PayPal API credentials. Try the example above with your own credentials to confirm that your Sandbox test accounts are set up.

Specifically, substitute your own Sandbox credentials and user-specific inputs in the Try It example and rerun it. If you have not yet set these up, do so now, as described in Testing Classic API Calls.

Additional resources

API reference:

Schema: