Initiate a payment

Call NVP/SOAP SetExpressCheckout to initiate the Express Checkout process and generate a token that tracks the customer throughout the entire checkout process.

Request

This example request specifies the minimum parameters for a sale payment:

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 You can make adjustments for shipping and tax later, if necessary.
RETURNURL The URL of the final review page on your website where the customer confirms the order and payment.
CANCELURL The URL of the original page on your website where the customer initially chose PayPal as a payment type.

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 The ID for this PayPal transaction. You must use this token in subsequent calls for this transaction.

Pass line items

In the SetExpressCheckout request, pass line items so your customer can see the transaction amount when he or she completes checkout on PayPal. If you do not pass line items, the total amount of the transaction is not displayed on the PayPal screen.

Tip: PayPal recommends that you pass 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.

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 renders this PayPal page. Customers can log in or click the shopping cart to view transaction details:

Line item calculation and order

This table describes how Express Checkout calculates line items and the order in which you pass them in the call:

Totals Algorithm Notes
Order total Item total + Tax total + Shipping total + Shipping discount amount None
Item total ITEM m] + ITEM m+1] + ITEM m+2] + ITEM[…] Where ITEM m] = L_PAYMENTREQUEST_<n>_AMT<m> * L_PAYMENTREQUEST_<n>_QTY<m>
Tax total Total tax, or the sum of all individual tax amounts If you specify L_PAYMENTREQUEST_<n>_TAXAMT<m> 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 must add up correctly.

If you do not specify L_PAYMENTREQUEST_<n>_TAXAMT<m> in your request, the tax total can equal anything.
Shipping total The cost to charge for shipping Line items have no impact on total.
Shipping discount amount The discount amount to apply to shipping Line items have no impact on the total.
Note: Mark the discount value as a negative amount. A positive value increases the order total.

Initialize the checkout flow

The token that the SetExpressCheckout response returns associates a customer to a particular Express Checkout transaction. You use this token in all subsequent calls for this transaction.

To initiate the checkout flow, pass the token to the client. For detailed instructions, see Advanced client-side integration.

Note: For existing integrations, you typically use the token from the SetExpressCheckout response to redirect the buyer to PayPal. PayPal recommends that you use the client-side checkout.js script integration. See PayPal Checkout Overview.

Additional information

Next

Get payment details and display it on your website.

Feedback