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 Checkout Integration Guide.
The SetExpressCheckout
call initiates the Express Checkout process and generates a token that tracks the buyer throughout the entire checkout process. In this call you:
Request
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).
Response
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
In the 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
SetExpressCheckout
call.
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]
+ITEM [m+1]
+ITEM [m+2]
+ITEM […]
where
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_TAXAMTm
for 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_TAXAMTm
in 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:
- Live:
https://www.paypal.com/checkoutnow?token=EC-XXXXXXXXXX
- Sandbox:
https://www.sandbox.paypal.com/checkoutnow?token=EC-XXXXXXXXX
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 TOKEN
and PayerID
in the query string. The return URL looks like this:
https://example.com/return?token=EC-7BX27754BT8623257&PayerID=UPGGM5VND8D5Q
TOKEN
— Tracks the entire transaction.PayerID
— Tracks the buyer who accepted to pay with PayPal.
Additional information
- SetExpressCheckout API Operation NVP/SOAP
- API error codes
- Express Checkout API flow
- Authorize and capture a payment
Next
To get buyer information and display it on your website, call get payment details.