How to Create and Process an Order Using Express Checkout

In Express Checkout, creating and processing an order requires:

  1. Setting up the order authorization.
  2. Redirecting the customer to PayPal.
  3. Obtaining the customer details.
  4. Confirming the order authorization.
  5. Authorizing the first payment (future).
  6. Capturing the first the payment (future).
  7. Repeating steps 5 and 6, as needed (future).

Below are samples that contain parameters for POST requests. For API credentials and endpoints, see Apps 101.

Prerequisites

Merchant Technical Support must grant your sandbox user permission for the number of authorizations you need to make (per order). For this example, your sandbox user must have permission to make two authorizations per order. No permission is needed for making one authorization per order.

For an overview of the Order payment action (used below), see Express Checkout Payment Actions. Also see PayPal Express Checkout Payment Actions.

Step 1: Set Up the Order Authorization

When a customer is ready for authorization, call SetExpressCheckout with the payment information. Also specify PAYMENTREQUEST_0_PAYMENTACTION=Order.

The SetExpressCheckout response contains a token for use in subsequent steps.

Request 
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=SetExpressCheckout
&VERSION=95
&PAYMENTREQUEST_0_PAYMENTACTION=Order    #Sets up an authorization for an order
&PAYMENTREQUEST_0_AMT=20    #The amount authorized
&PAYMENTREQUEST_0_CURRENCYCODE=USD    #The currency, e.g. US dollars
&cancelUrl=http://www.yourdomain.com/cancel.html
&returnUrl=http://www.yourdomain.com/success.html

Response
--------
TOKEN=EC%2d40319508UX6051234
&ACK=Success
...

Step 2: Redirect the Customer to PayPal

Redirect the customer to Paypal by using the token from Step 1 with the PayPal authorization URL, as follows:

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

If the customer doesn't authorize the order, they are redirected to the cancel URL that you specified in the SetExpressCheckout call, so you can provide a way to re-initiate authorization.

Step 3: Obtain the Customer Details

If the customer approves the order, they are redirected to the return URL (specified in SetExpressCheckout), appended with the token from Step 1.

Call GetExpressCheckoutDetails to obtain a PayerID value, which uniquely identifies the customer.

In the sample code below, insert the token from Step 1 after you URL-decode the token string.

Request 
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=GetExpressCheckoutDetails
&VERSION=95
&TOKEN=EC-40319508UX6051234    #URL-decoded token obtained in the SetExpressCheckout response

Response
--------
TOKEN=EC%2d40319508UX6051234
&ACK=Success
&PAYERID=3TXTXECKF1234    #Customer account ID, for use in the DoExpressCheckoutPayment call
...

Step 4: Confirm the Order Authorization

Call DoExpressCheckoutPayment, specifying a PayerID (from the GetExpressCheckoutDetails response). Also specify PAYMENTREQUEST_0_PAYMENTACTION=Order, along with the token from Step 1.

The DoExpressCheckoutPayment response contains an authorization ID (as PAYMENTINFO_0_TRANSACTIONID), for URL-decoding and future use when you authorize a payment (e.g. in Step 5).

For more information, see the DoExpressCheckoutPayment API Operation.

Request 
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=DoExpressCheckoutPayment
&VERSION=95
&TOKEN=EC-40319508UX6051234    #URL-decoded token obtained from the SetExpressCheckout response
&PAYERID=3TXTXECKF1234    #Customer account ID, obtained from the GetExpressCheckoutDetails response
&PAYMENTREQUEST_0_PAYMENTACTION=Order    #Creates an order, including an agreement to pay multiple authorized amounts 
&PAYMENTREQUEST_0_AMT=20    #The amount authorized for the order
&PAYMENTREQUEST_0_CURRENCYCODE=USD

Response
--------
TOKEN=EC%2d40319508UX6051234
&ACK=Success
&PAYMENTINFO_0_TRANSACTIONID=O%2d2GN90824037101234   #URL-decode this value for use in the DoAuthorization API calls
&PAYMENTINFO_0_ORDERTIME=2012%2d10%2d31T00%3a43%3a00Z
&PAYMENTINFO_0_AMT=20%2e00
&PAYMENTINFO_0_SECUREMERCHANTACCOUNTID=QJSRDC4JW1234
&PAYMENTINFO_0_ACK=Success
...

Step 5: Authorize the First Payment (Future)

Call DoAuthorization to authorize the first payment. In the TRANSACTIONID field, specify the URL-decoded value of the DoExpressCheckoutPayment response's PAYMENTINFO_0_TRANSACTIONID field.

In the DoAuthorization response, save the value of the TRANSACTIONID output field for Step 6.

Request 
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=DoAuthorization
&VERSION=95
&TRANSACTIONID=O-2GN90824037101234    #URL-decoded value of PAYMENTINFO_0_TRANSACTIONID field, from the DoExpressCheckoutPayment response
&AMT=11    #Amount of this authorization
&CURRENCYCODE=USD

Response
--------
TRANSACTIONID=75324566RU7001234    #For use in a DoCapture API call
&AMT=11%2e00
&CURRENCYCODE=USD
&ACK=Success
&PAYMENTSTATUS=Pending
&PENDINGREASON=authorization
...

Step 6: Capture the First Payment (Future)

Call DoCapture. For the AUTHORIZATIONID value, specify the TRANSACTIONID value (from the DoAuthorization response in Step 5).

Also specify COMPLETETYPE=NotComplete, since another authorization will occur for this order, as shown in Step 7. Specifying COMPLETETYPE=NotComplete keeps the order open for future authorizations. Specify COMPLETETYPE=Complete if you want to prevent more authorizations on the order.

For information about payment capture, and on holding funds and the validity of an authorization, see PayPal Express Checkout Payment Actions.

Request 
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=DoCapture
&VERSION=95
&AUTHORIZATIONID=75324566RU7001234    #Specify the DoAuthorization response's TRANSACTIONID value
&AMT=11
&CURRENCYCODE=USD
&COMPLETETYPE=NotComplete    #If more authorizations will occur for this order, specify NotComplete; otherwise, specify Complete 

Response
--------
AUTHORIZATIONID=75324566RU7001234
&ACK=Success
&TRANSACTIONID=0HL73671RY5781234
&PARENTTRANSACTIONID=75324566RU7001234
&TRANSACTIONTYPE=expresscheckout
&PAYMENTTYPE=instant
&ORDERTIME=2012%2d10%2d31T00%3a49%3a28Z
&AMT=11%2e00
&FEEAMT=0%2e62
&TAXAMT=0%2e00
&CURRENCYCODE=USD
&PAYMENTSTATUS=Completed
...

Step 7: Repeat Steps 5 and 6, as Needed

Repeat the authorization and capture steps (that is, steps 5 and 6), as needed. If more authorizations are needed, then in your DoCapture call, specify COMPLETETYPE=NotComplete. On the last DoCapture call you make, specify COMPLETETYPE=Complete (since no more authorizations would be needed for the order).