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:

  1. Log in.
  2. Select a shipping option and their funding source.
  3. 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

Next

To get buyer information and display it on your website, call get payment details.

Popular Search Queries
PayPal Help
FAQ's

FAQ's

Forum

Tech Support Community

PayPal Community