Customizing Express Checkout

You can set parameters in your Express Checkout API requests to make these customize the buyer's checkout experience:

You can include your company logo at the top of PayPal checkout pages.

To include your logo:

  1. Create a logo image up to 90 pixels wide by 60 pixels high and save it in a valid graphics format, such as .gif, .jpg, or .png.
  2. Store the URL to the image on a secure (HTTPS) server.
  3. Assign the URL to the LOGOIMG parameter for NVP, or the cpp-logo-image parameter for SOAP, in the SetExpressCheckout. For example:
&LOGOIMG=https://www.../YourLogo.gif

Note: You can also specify your company logo in your PayPal account Profile. If you specify LOGOIMG in your Expresss Checkout API call, it overrides the image stored in your account Profile.

Provide line item details

After a buyer logs in to PayPal to check out, you can display detailed information for each item being purchased.

You can include these details for each item:

Item name Identifies the item and distinguishes it from other line items in the order.
Item description Identifies which of several items the buyer is purchasing. For example, you may be offering an item in different sizes. Knowing the size helps the buyer decide whether the one they selected was appropriate. If the item is an eBay auction item, it is recommended that you provide the phrase "eBay item" in this field.
Item number Identifies an item by a number. If the item is an eBay auction item, it is recommended that you provide the eBay item number in this field.
Item unit price Specifies exactly how much one unit of the item costs. It can be a positive or negative value but not zero.
Item unit quantity Identifies the number of units the buyer is ordering. PayPal calculates the total as the product of line-item unit price and line-item unit quantity. You can also show other detailed information about the order:
  • Item total and tax. Reflects total of all items in the order and the tax, respectively.
  • Shipping and handling. Reflects the sum of the shipping and handling amounts. You must determine actual shipping and handling amounts.
  • Shipping discount. Appears as a credit in this field if the buyer is receiving a discount on shipping.
  • Insurance. Shows the insurance fee when there is insurance on shipping.
  • Total. Reflects the total of the order, including shipping, handling, tax, and other price adjustment-related items.

Note: The Enter gift certificate, reward, or discount link enables the buyer to redeem certificates, rewards, or discounts that PayPal issues. The link does not enable the buyer to redeem incentives that you issue.

Order detail parameters

To provide order details as part of the buyer's checkout experience, pass any of these parameters with SetExpressCheckout.

Note: PayPal recommends passing the same order details in the DoExpressCheckoutPayment call.

NVP field SOAP field Description and comments
L_PAYMENTREQUEST_n_NAMEm Name Item name.
L_PAYMENTREQUEST_n_NUMBERm Number Item number.
L_PAYMENTREQUEST_n_DESCm Description Item description. The DESC (NVP) and OrderDescription (SOAP) fields still exist for backwards compatibility. However, L_DESCn and Description enable you to provide a more precise description for each different item purchased, such as hiking boots or cooking utensils rather than one general purpose description such as camping supplies.
L_PAYMENTREQUEST_n_AMTm Amount Item unit price. PayPal calculates the product of the item unit price and item unit quantity (below) in the Amount column of the cart review area. The item unit price can be a positive or a negative value, but not 0. You may provide a negative value to reflect a discount on an order, for example.
L_PAYMENTREQUEST_n_QTYm Quantity Item unit quantity.
PAYMENTREQUEST_n_ITEMAMT ItemTotal Sum of costs of all items in this order.
PAYMENTREQUEST_n_TAXAMT TaxTotal Sum of tax for all items in this order.
PAYMENTREQUEST_n_SHIPPINGAMT ShippingTotal Total shipping cost for this order (8). PayPal calculates the sum of the shipping cost and the handling cost. Although you may change the value later, try to pass in a shipping amount that is reasonably accurate.
PAYMENTREQUEST_n_HANDLINGAMT HandlingTotal Total handling cost for this order.
PAYMENTREQUEST_n_SHIPDISCAMT ShippingDiscount Shipping discount for this order. You specify this value as a negative number.
PAYMENTREQUEST_n_INSURANCEAMT InsuranceTotal Total shipping insurance cost for this order.
PAYMENTREQUEST_n_AMT OrderTotal Total of order, including shipping, handling, tax, and any other billing adjustments such as a credit due.

If you pass the generic order description parameter (PAYMENTREQUEST_n_DESC) along with any two of the following line-item parameters, the order description value does not display.

  • L_PAYMENTREQUEST_n_NAMEm
  • L_PAYMENTREQUEST_n_NUMBERm
  • L_PAYMENTREQUEST_n_DESCm

This example shows how to set line-item parameters in the SetExpressCheckout call.

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=http://...
&CANCELURL=http://...
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&L_PAYMENTREQUEST_0_NAME0=10% Decaf Kona Blend Coffee
&L_PAYMENTREQUEST_0_NUMBER0=623083
&L_PAYMENTREQUEST_0_DESC0=Size: 8.8-oz
&L_PAYMENTREQUEST_0_AMT0=9.95
&L_PAYMENTREQUEST_0_QTY0=2
&L_PAYMENTREQUEST_0_NAME1=Coffee Filter bags
&L_PAYMENTREQUEST_0_NUMBER1=623084
&L_PAYMENTREQUEST_0_DESC1=Size: Two 24-piece boxes
&L_PAYMENTREQUEST_0_AMT1=39.70
&L_PAYMENTREQUEST_0_QTY1=2
&PAYMENTREQUEST_0_ITEMAMT=99.30
&PAYMENTREQUEST_0_TAXAMT=2.58
&PAYMENTREQUEST_0_SHIPPINGAMT=3.00
&PAYMENTREQUEST_0_HANDLINGAMT=2.99
&PAYMENTREQUEST_0_SHIPDISCAMT=-3.00
&PAYMENTREQUEST_0_INSURANCEAMT=1.00
&PAYMENTREQUEST_0_AMT=105.87
&PAYMENTREQUEST_0_CURRENCYCODE=USD

Change the locale

You can change the locale of PayPal pages to match the language on your website using either a 2-character country code or a 5-character locale code from the supported codes listed on the NVP/SOAP API locale codes page. To change the language displayed on the PayPal pages, set the LOCALECODE parameter to one of the allowable values in the SetExpressCheckout call.

This example sets LOCALCODE to ES for Spain.

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE=EUR
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&LOCALECODE=ES

Manage shipping addresses

You can use one of these options to handle a buyer's shipping address:

Require a confirmed shipping address

A confirmed address is one that PayPal has established as belonging to the PayPal account holder. PayPal's Seller Protection Policy requires a confirmed shipping address.

Note: Because buyers may prefer to ship to a non-confirmed address, to ship a gift for example, PayPal does not recommend requiring a confirmed address unless you are selling high-risk merchandise. If you prefer to use confirmed addresses, do not set ADDROVERRIDE.

To require a confirmed address, ensure that the shipping address matches the address on record with PayPal. You can do this through your account Profile, as described in Blocking payments from payers without a confirmed address in the Merchant Setup and Administration Guide.

This example request shows how to require a confirmed address for shipping:

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&PAYMENTREQUEST_0_SHIPTOSTREET=1 Main St
&PAYMENTREQUEST_0_SHIPTOCITY=San Jose
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95131
&PAYMENTREQUEST_0_SHIPTOPHONENUM=408-967-4444

Suppress the shipping address

If you sell a product or service that does not require shipping or you prefer to handle addresses completely on your own and do not want to let buyers choose from their PayPal address book, you can suppress the display of the buyer's shipping address. To suppress the shipping address, set the NOSHIPPING parameter to 1 in the SetExpressCheckout call.

This example call suppresses the shipping address:

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&NOSHIPPING=1
&PAYMENTREQUEST_0_SHIPTONAME=J Smith
&PAYMENTREQUEST_0_SHIPTOSTREET=1 Main St
&PAYMENTREQUEST_0_SHIPTOCITY=San Jose
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95131
&PAYMENTREQUEST_0_SHIPTOPHONENUM=408-967-4444

Override the shipping address

If your website registration requests the buyer's shipping address, you can override the buyer's shipping address stored on PayPal. This replaces it with one you specify in the SetExpressCheckout call. The buyer cannot edit the overridden address.

Note: If you prefer to override addresses, PayPal recommends that you do not require confirmed addresses.

To override the shipping address set the ADDROVERRIDE parameter to 1 and the following shipping address parameters in the SetExpressCheckout call:

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&ADDROVERRIDE=1
&PAYMENTREQUEST_0_SHIPTOSTREET=1 Second St
&PAYMENTREQUEST_0_SHIPTOSTREET2=Ste 210
&PAYMENTREQUEST_0_SHIPTOCITY=San Jose
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95131
&PAYMENTREQUEST_0_SHIPTOPHONENUM=408-967-4444

Automatically fill out shipping and contact information

When you pass the buyer's shipping address, telephone number and email address in the SetExpressCheckout call, PayPal automatically fills out this information in the debit or credit card form fields on the PayPal page.

After the SetExpressCheckout call, the buyer is redirected to the PayPal. Buyers with a PayPal account can log in with their email address and password. Buyers who do not have an account can use their debit or credit card to pay and will have their shipping and contact information filled out.

This example call automatically fills out the buyer's shipping and contact information:

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&PAYMENTREQUEST_0_SHIPTOSTREET=1 Main Street
&PAYMENTREQUEST_0_SHIPTOCITY=San Jose
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95131
&PAYMENTREQUEST_0_EMAIL=jsmith01@example.com
&PAYMENTREQUEST_0_SHIPTOPHONENUM=408-559-5948

This figure shows the Pay with debit or credit card section expanded with the buyer shipping and contact fields filled out.

Auto-fill form

Allow buyers to complete purchases on PayPal

You can shorten the Express Checkout flow and let buyers complete their purchases on PayPal. Then, you can skip your order confirmation page.

Generally, buyers select payment methods as the last step before they complete their purchases. If you collect no additional information after buyers return from PayPal, you can skip the confirm-order page on your website. If you collect additional information that does not affect the payment, PayPal recommends that you collect it after buyers complete their purchases.

The useraction URL parameter in your redirect to PayPal determines whether buyers complete their purchases on PayPal or on your website. If you set useraction to commit, PayPal sets the button text to Pay Now on the PayPal Review your informaton page. This text lets buyers know that they complete their purchases if they click the button.

The following sample code shows the redirect to let buyers pay on PayPal:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=commit&token=valueFromSetExpressCheckoutResponse

Additional information

  • GetExpressCheckoutDetails NVP/SOAP
  • [DoExpressCheckoutPayment]