How to Authorize and Process a Payment Using Express Checkout

In Express Checkout, authorizing and processing a payment requires:

  1. Setting up the payment authorization.
  2. Redirecting the customer to PayPal.
  3. Obtaining the customer details.
  4. Confirming the payment authorization.
  5. Capturing the payment (future).

For background information, see:

Note: Below are samples that contain parameters for POST requests.

Step 1: Set Up the Payment Authorization

When a customer is ready for authorization, call SetExpressCheckout and specify PAYMENTREQUEST_0_PAYMENTACTION=Authorization. For more information, see PayPal Express Checkout Payment Actions and the SetExpressCheckout API Operation.

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=Authorization    #Sets up authorization for a single future payment
&PAYMENTREQUEST_0_AMT=1    #The amount authorized
&PAYMENTREQUEST_0_CURRENCYCODE=USD    #The currency, e.g. US dollars
&cancelUrl=http://www.yourdomain.com/cancel.html    #For use if the customer decides not to proceed with payment
&returnUrl=http://www.yourdomain.com/success.html   #For use if the customer proceeds with payment

Response
--------
TOKEN=EC%2d470284976K7901234
&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 approve of the payment authorization, the customer is 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 of the payment authorization, the customer is 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. For parameter descriptions, see the GetExpressCheckoutDetails API Operation.

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-470284976K7901234

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

Step 4: Confirm the Payment Authorization

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

The DoExpressCheckoutPayment response contains an authorization ID (as PAYMENTINFO_0_TRANSACTIONID), for future use when you capture the payment (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-470284976K7901234    #Token from the SetExpressCheckout response
&PAYERID=3TXTXECKFU1234    #Customer account ID, from the GetExpressCheckoutDetails response
&PAYMENTREQUEST_0_PAYMENTACTION=Authorization    #Enables you to collect payment in the future
&PAYMENTREQUEST_0_AMT=1
&PAYMENTREQUEST_0_CURRENCYCODE=USD

Response
--------
TOKEN=EC%2d470284976K7901234
&ACK=Success
&VERSION=95
&PAYMENTINFO_0_TRANSACTIONID=20K92515TX2901234    #Use this value as the authorization ID in a DoCapture request
&PAYMENTINFO_0_SECUREMERCHANTACCOUNTID=QJSRDC4JW1234
&PAYMENTINFO_0_ACK=Success
...

Step 5: Capture the Payment (Future)

Call DoCapture, specifying a value for AUTHORIZATIONID. The value for AUTHORIZATIONID is the value of PAYMENTINFO_0_TRANSACTIONID (from Step 4).

For information on 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=20K92515TX2901234    #Authorization ID. Specify the value of PAYMENTINFO_0_TRANSACTIONID from the DoExpressCheckoutPayment response)
&AMT=1    #The amount of the payment
&CURRENCYCODE=USD
&COMPLETETYPE=Complete    #Indicates that for the authorization specified, this is the last payment capture

Response
--------
AUTHORIZATIONID=20K92515TX2901234
&ACK=Success
&TRANSACTIONID=2KF46316MJ7751234    #New transaction ID for this payment
&PARENTTRANSACTIONID=20K92515TX2901234    #Same as the ID of the original authorization
&TRANSACTIONTYPE=expresscheckout
&PAYMENTTYPE=instant
&AMT=1%2e00
&FEEAMT=0%2e33
&TAXAMT=0%2e00
&CURRENCYCODE=USD
&PAYMENTSTATUS=Completed
...