Customizing Express Checkout
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 Subscriptions Integration Guide.
You can make these customizations to the buyer's checkout experience:
- Include your company logo
- Provide line item details
- Change the locale
- Manage shipping addresses
- Automatically fill out shipping and contact information
- Display a Pay Now button
Include your company logo
You can include your company logo at the top of PayPal checkout pages.
- 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.
- Store the URL to the image on a secure (HTTPS) server.
- Assign the URL to the
LOGOIMGparameter for NVP, or the
cpp-logo-imageparameter for SOAP, in the
SetExpressCheckout. For example:
Note: You can also specify your company logo in your PayPal account Profile. If you specify
LOGOIMGin your Express Checkout API call, it overrides the image stored in your account Profile.
Provide line item details
After a buyer logs in to PayPal, you can show line item details:
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.
|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:
Note: The buyer can click the Enter gift certificate, reward, or discount link to redeem certificates, rewards, or discounts that PayPal issues, but not merchant-issued incentives.
Order detail parameters
To include order details as part of the buyer's checkout experience, call the
DoExpressCheckoutPayment operations with these parameters:
|NVP field||SOAP field||Description and comments|
Item description. The
||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.|
||Item unit quantity.|
||Sum of costs of all items in this order.|
||Sum of tax for all items in this order.|
||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.|
||Total handling cost for this order.|
||Shipping discount for this order. You specify this value as a negative number.|
||Total shipping insurance cost for this order.|
||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.
This example shows how to set line-item parameters in the
[requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &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
This example sets
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
To require a confirmed address, the shipping address must match the PayPal address on record. For information, see Block 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=555-123-4444
Suppress the shipping address
You can suppress the display of the buyer's shipping address. You might do this if you sell a product or service that does not require shipping or if you want to handle shipping addresses separately. To suppress the shipping address, set the
NOSHIPPING parameter to
1 in the
[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=555-123-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
[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=555-123-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.
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_EMAILemail@example.com &PAYMENTREQUEST_0_SHIPTOPHONENUM=555-123-4444
This figure shows the Pay with debit or credit card section expanded with the buyer shipping and contact fields filled out.
Display a Pay Now button
You can expedite the checkout flow by letting a buyer skip your order confirmation page and complete their purchase on PayPal.
Generally, a buyer selects a payment method as the last step before they complete their purchase. If you collect no additional information after a buyer returns 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 the buyer completes their purchases.
useraction query parameter determines whether a buyer completes their purchase on PayPal or on your website. You can include or omit this parameter from the URL query string:
- If you include
useraction=commitin the query string, the flow redirects the buyer to the PayPal payment page and displays a Pay Now button. When the buyer clicks Pay Now, PayPal redirects the buyer back to your site, at which point you call
DoExpressCheckoutPaymentto complete the payment without additional interaction from the buyer. Choose this flow when you know the final payment amount when you initiate the checkout flow.
- If you omit
useractionfrom the query string, the default flow redirects the buyer to the PayPal payment page and displays the Continue button. When the buyer clicks Continue, they can edit the payment amount. Choose this flow when you do not know the final payment amount when you initiate the checkout flow.
The following sample code shows the redirect to let buyers pay on PayPal: