How to Use Express Checkout to Create One-Time Payments
Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.
Learn how to complete an Express Checkout transaction by using the Set-Get-Do series of API operations.
For demonstration purposes, the following sample requests use the PayPal sandbox. To use the NVP/SOAP APIs to make these calls, see Apps 101.
The following figure shows the flow of calls through a typical Express Checkout transaction. It illustrates how the transaction flow interacts with the PayPal customer and how your requests interact with PayPal (the sandbox in this example).
The numbers in the diagram correspond to the following steps:
|1.||Set up payment information.|
|2.||PayPal returns a token.|
|3.||Redirect the customer to PayPal for approval.|
|4.||PayPal redirects the customer back to your site.|
|5.||Obtain approved payment details.|
|6.||Complete the transaction.|
Set up payment information
When a customer initiates a check out, call
SetExpressCheckout to specify the payment action, amount of payment, return URL, and cancel URL.
curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=<callerID> # User ID of the PayPal caller account \ -d PWD=<callerPswd> # Password of the caller account \ -d SIGNATURE=<callerSig> # Signature of the caller account \ -d METHOD=SetExpressCheckout \ -d VERSION=93 \ -d PAYMENTREQUEST_0_PAYMENTACTION=SALE # type of payment \ -d PAYMENTREQUEST_0_AMT=19.95 # amount of transaction \ -d PAYMENTREQUEST_0_CURRENCYCODE=USD # currency of transaction \ -d RETURNURL=https://example.com/success # payment confirmation URL \ -d CANCELURL=https://example.com/cancel # payment cancellation URL
Note: Example calls are shown in cURL, and the code is wrapped and commented for readability.
SetExpressCheckout response contains a token value that you use in subsequent calls to complete the transaction:
PayPal returns a token
SetExpressCheckout request succeeds, PayPal returns a token string in the
Token response field. The default lifetime of this token is three hours. You need this token in the subsequent steps.
Important: You must URL-decode the returned token value before you can use it in other Express Checkout calls.
Redirect the customer to PayPal for approval
Using the token valued returned from
SetExpressCheckout, redirect the customer to PayPal so they can approve the transaction:
The redirect presents the customer with a PayPal log-in page. After the customer logs in, PayPal displays the transaction details on the Payments Review page. The customer approves the payment on this page by clicking Continue.
PayPal redirects the customer back to your site
If the customer approves the payment, PayPal directs the customer to the payment confirmation page (the return URL specified in your
SetExpressCheckout call in Step 1). If the customer doesn't authorize the payment, PayPal directs the customer to the cancel URL that you also specified in your
SetExpressCheckout call, and you can attempt to re-initiate the checkout.
Obtain approved payment details
If the customer approves the payment, call
GetExpressCheckoutDetails to obtain the
PayerID (which uniquely identifies the customer), and any other details you might need for transaction processing. For example, you can use the transaction details to display the customer's shipping data, and other information, on your payment confirmation page.
Use the following sample by replacing
<tokenValue> with the token from the
curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=<callerID> \ -d PWD=<callerPswd> \ -d SIGNATURE=<callerSig> \ -d METHOD=GetExpressCheckoutDetails \ -d VERSION=93 \ -d TOKEN=<tokenValue>
The response from this call includes the
PayerID value, which you need to capture the payment:
TOKEN=EC%2d4RX1920730957200V ... &PAYERID=6B9DKHQRKW4SG ...
Complete the transaction
In addition to the transaction details, your payment confirmation page should include a Confirm button. When the customer confirms the payment, call
DoExpressCheckoutPayment to capture (collect) the payment. The following sample shows how to specify the
PayerID and token value returned from the previous calls:
curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=<callerID> \ -d PWD=<callerPswd> \ -d SIGNATURE=<callerSig> \ -d METHOD=DoExpressCheckoutPayment \ -d VERSION=93 \ -d TOKEN=<tokenValue> \ -d PAYERID=<payerID> # customer's unique PayPal ID \ -d PAYMENTREQUEST_0_PAYMENTACTION=SALE # payment type \ -d PAYMENTREQUEST_0_AMT=19.95 # transaction amount \ -d PAYMENTREQUEST_0_CURRENCYCODE=USD # transaction currency
When PayPal processes
DoExpressCheckoutPayment, it captures the payment by transferring the funds from the customer account to the appropriate merchant account and sends a confirmation e-mail to the customer.