How to Authorize and Process a Payment Using Express Checkout
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.
In Express Checkout, authorizing and processing a payment requires:
- Setting up the payment authorization.
- Redirecting the customer to PayPal.
- Obtaining the customer details.
- Confirming the payment authorization.
- Capturing the payment (future).
For background information, see:
- Apps 101 — For API credentials and endpoints.
- Express Checkout Overview
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=https://example.com/cancel #For use if the customer decides not to proceed with payment
&returnUrl=https://example.com/success #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
...