Initiate a payment
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 Express Checkout Integration Guide.
SetExpressCheckout call initiates the Express Checkout process and generates a token that tracks the buyer throughout the entire checkout process. In this call you:
This example request specifies the minimum parameters for a sale payment. To view the full Express Checkout API flow for a sale transaction, see Express Checkout API flow.
USER=xxxxxxxx PWD=xxxxxxx SIGNATURE=xxxxxxxxx METHOD=SetExpressCheckout VERSION=124.0 RETURNURL=https://example.com/return CANCELURL=https://example.com/cancel PAYMENTREQUEST_0_PAYMENTACTION=Sale PAYMENTREQUEST_0_AMT=524.20 PAYMENTREQUEST_0_CURRENCYCODE=USD PAYMENTREQUEST_0_DESC=test EC payment
Variables in this example:
AMT— Adjustments for shipping and tax can be made later, if necessary.
RETURNURL— URL of the final review page on your website where the buyer confirms the order and payment. See Redirect the buyer to PayPal.
CANCELURL— URL of the original page on your website where the buyer initially chose PayPal as a payment type.
For detailed reference information, see SetExpressCheckout API Operation (NVP).
TOKEN=EC-72D0681527109671C TIMESTAMP=2015-10-22T00:50:09Z CORRELATIONID=b09c3beb8aec4 ACK=Success VERSION=124.0 BUILD=18308778
Important response fields:
ACK— Indicates success or failure for the request.
TOKEN— Identifier for this PayPal transaction. You must use this token in subsequent calls for this transaction.
Pass line items in SetExpressCheckout
SetExpressCheckout request, pass line items so your buyer can see the transaction amount when completing their checkout on PayPal. If you do not pass line items, the total amount of the transaction will not be displayed on the In-Context PayPal screen.
Tip: As a best practice, PayPal recommends passing line items in the
Note: If you provide PayPal a user's itemized shopping cart list and a mismatch occurs between the sum of those items and the transaction total, PayPal processes the transaction using the sum of the cart items only when the difference is within $0.50.
How line items are calculated and the order in which you should pass them in the call:
Order Total = Item Total + Tax Total + Shipping Total + Shipping Discount Amount
Item Total =
ITEM[m] = L_PAYMENTREQUEST_n_AMTm *L_PAYMENTREQUEST_n_QTYm
Tax Total = Total tax, or the sum of all individual tax amounts
If you specify
L_PAYMENTREQUEST_n_TAXAMTmfor items, the Tax Total must be the sum of all specified individual tax amounts.
You do not need to specify tax for any items, but the sum still needs to add up correctly. If you do not specify
L_PAYMENTREQUEST_n_TAXAMTmin your request, Tax Total can equal anything.
Shipping Total = The cost you want to charge for shipping. Line items have no impact on this.
Shipping Discount Amount = The discount amount you want to apply to shipping. Line items have no impact on this.
Note: If you specify a positive value, this will increase the order total, so remember to mark the discount value as a negative amount.
Line item example
This request snippet shows all line item parameters:
// Order totals PAYMENTREQUEST_0_AMT=4 PAYMENTREQUEST_0_ITEMAMT=2 PAYMENTREQUEST_0_SHIPPINGAMT=1 PAYMENTREQUEST_0_TAXAMT=2 PAYMENTREQUEST_0_SHIPDISCAMT=-1 //negative value // Line item 1 details L_PAYMENTREQUEST_0_NAME0=item1 L_PAYMENTREQUEST_0_DESC0=item1 description L_PAYMENTREQUEST_0_AMT0=1 L_PAYMENTREQUEST_0_QTY0=1 L_PAYMENTREQUEST_0_TAXAMT0=1 L_PAYMENTREQUEST_0_NUMBER0=a L_PAYMENTREQUEST_0_ITEMURL0=https://example.com/item=B L_PAYMENTREQUEST_0_ITEMCATEGORY0=Physical // Line item 2 details L_PAYMENTREQUEST_0_NAME1=item2 L_PAYMENTREQUEST_0_DESC1=item2 description L_PAYMENTREQUEST_0_AMT1=1 L_PAYMENTREQUEST_0_QTY1=1 L_PAYMENTREQUEST_0_TAXAMT1=1 L_PAYMENTREQUEST_0_NUMBER1=b L_PAYMENTREQUEST_0_ITEMURL1=https://example.com/item=B L_PAYMENTREQUEST_0_ITEMCATEGORY1=Physical
The example snippet results in this PayPal page. Buyers can log in or click the shopping cart to view transaction details:
Redirect the buyer to PayPal
The token returned in the
SetExpressCheckout response associates a buyer to a particular Express Checkout transaction. You use this token in all subsequent calls for this transaction.
Once you receive the
SetExpressCheckout response, you redirect the buyer to PayPal by appending the token to a predetermined URL. The final URL looks like this:
Once the buyer is on the PayPal website, they will:
- Log in.
- Select a shipping option and their funding source.
- Click Continue to return to your website.
To specify the return URL in the
SetExpressCheckout API request, append the
PayerID in the query string. The return URL looks like this:
TOKEN— Tracks the entire transaction.
PayerID— Tracks the buyer who accepted to pay with PayPal.
- SetExpressCheckout API Operation NVP/SOAP
- API error codes
- Express Checkout API flow
- Authorize and capture a payment
To get buyer information and display it on your website, call get payment details.