Home
  • Payments and Transfers
  • Disputes and Limitations
  • My Account
  • My Wallet
  • Login & Security
  • Seller Tools

How do I create a one-time payment with Checkout?

This article describes how to complete a Checkout transaction using the Set-Get-Do series of API operations.

For demonstration purposes, this article makes requests using the PayPal Sandbox. For information on making calls using the NVP/SOAP APIs, including obtaining the needed API credentials and how to make test calls using the Sandbox.

The following figure shows the flow of calls through a typical 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).
 
Set up the payment information

When a customer initiates a checkout, 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=http://www.example.com/success.html  # URL of your payment confirmation page \
  -d CANCELURL=http://www.example.com/cancel.html   # URL redirect if customer cancels payment

(Example calls are shown in cURL, and the code is wrapped and commented for readability.)

The SetExpressCheckout response contains a token value that you'll use in subsequent calls to complete the transaction.
PayPal returns a token

If the SetExpressCheckout request succeeds, PayPal returns a token string in the Token response field. The default lifetime of this token is three hours. You'll need this token in the subsequent steps.

# SetExpressCheckout response
...

TOKEN=EC%2d4RX1920730957200V
...


(You must URL-decode the returned token value before you can use it in other Checkout calls.)
Redirect the customer to PayPal for approval

Using the token value returned from SetExpressCheckout, redirect the customer to PayPal so they can approve the transaction:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=tokenValue

The redirect presents the customer with a PayPal login 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 sends 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). 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 try to reinitiate 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 SetExpressCheckoutPayment response:
 
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 is needed to capture the payment:
 
# GetExpressCheckoutDetails response 
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 example 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, e.g. US dollars

When PayPal processes DoExpressCheckoutPayment, it captures the payment by transferring the funds from the customer account to the appropriate merchant account and sends the customer a confirmation email.


See also:
PayPal Checkout Integration
Best Practices Guide
Was this article helpful?

More ways we can help

How are we doing?
Take our survey

We'll use cookies to improve and customise your experience if you continue to browse. Is it OK if we also use cookies to show you personalised ads? Learn more and manage your cookies