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.
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.
SetExpressCheckoutto set up the transaction and define the URL to which the customer is returned after the customer authorizes payment.
- Redirect the customer to PayPal for authorization of the payment.
GetExpressCheckoutDetailsto obtain customer information, e.g. for customer review before payment.
DoExpressCheckoutPaymentto complete the transaction.
You can make calls in these formats:
|Request method||Request format||Response format|
|HTTP POST||Name/value pairs||Name/value pairs|
|HTTP POST||SOAP (1.1, 1.2)||SOAP|
Note: PayPal will no longer support the use of the GET HTTP request method for our classic NVP/SOAP APIs. For more information, including the planned change date, see Discontinue Use of GET Method for Classic APIs Microsite. Ensure that your API requests only use the POST HTTP request method by the specified date.
There are calls you can make to handle exceptions, e.g. you can void a transaction when a buyer cancels out of checkout.
Make 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.
Obtain the endpoint for the service and environment you are addressing.
This is the endpoint for making calls in name/value pair style in the Sandbox. For the SOAP endpoint, see API endpoints.
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
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
Make the call. (For an example, see Try It below.)
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. )
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.
Copy this cURL command:
curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=platfo_1255077030_biz_api1.gmail.com \ -d PWD=1255077037 \ -d SIGNATURE=Abg0gYcQyxQvnf2HDJkKtA-p6pqhA1k-KTYE0Gcy1diujFio4io5Vqjf \ -d METHOD=SetExpressCheckout \ -d VERSION=78 \ -d PAYMENTREQUEST_0_PAYMENTACTION=SALE \ -d PAYMENTREQUEST_0_AMT=19 \ -d PAYMENTREQUEST_0_CURRENCYCODE=USD \ -d cancelUrl=http://www.example.com/cancel.html \ -d returnUrl=http://www.example.com/success.html
Run the cURL command. (If the curl command is not found on your computer, download the free cURL executable.)
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 PayPal Sandbox Testing Guide.
Integrating In-Context Checkout
The new In-Context Express Checkout helps improve conversion rates with an easier way to pay online. The simplified design speeds buyers through payment in as few as 1 or 2 clicks — without leaving your website — for a secure and seamless checkout. On Macs and PCs, the in-context checkout window keeps the merchant website in view while providing customers with a streamlined and tightly-integrated checkout experience. Smartphones and tablets display an optimized full-page checkout window.
A few additional integration steps are required for in-context checkout. See the integration details.
- You can choose to download the Merchant API SDK. See NVP/SOAP API SDKs for information about the SDKs.
- Main WSDL: https://www.paypalobjects.com/wsdl/PayPalSvc.wsdl
- Referenced XSD: https://www.paypalobjects.com/wsdl/eBLBaseComponents.xsd
- Referenced XSD: https://www.paypalobjects.com/wsdl/CoreComponentTypes.xsd
- Referenced XSD: https://www.paypalobjects.com/wsdl/EnhancedDataTypes.xsd