Implement the Instant Update API

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 Instant Update API enables you to specify a URL with which PayPal can call your callback server with the buyer's shipping address, so you can provide the buyer with more detailed shipping, insurance, and tax information.

The Instant Update API is a server call to your callback server that instantly updates PayPal pages and enhances the Express Checkout experience on the Review your information page.

How the Instant Update API works

  1. When a buyer logs in to PayPal, the PayPal server calls your callback server with the buyer's default shipping address, which is stored in the PayPal system.
  2. Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
  3. PayPal displays this information in the cart review area so buyers can choose from the options.
  4. The buyer's final choices are returned in the GetExpressCheckoutDetails response.

Integration steps

To integrate the Instant Update API, you must modify Express Checkout API calls:

Step Description
1. Set up a secure, fast web service to accept HTTP requests from PayPal. On the live site, you must secure it by means of SSL/TLS through HTTPS.
2. Enable the callback service to process PayPal requests and return responses.
3. Modify these Express Checkout API calls with new parameters:
  • SetExpressCheckout. Send the callback URL, shipping, insurance, and tax information to PayPal.
  • GetExpressCheckoutDetails. Get the buyer's final choices for shipping and insurance, if applicable.
  • DoExpressCheckoutPayment. Set the buyer's final selections.
4. Eliminate your shipping options page.
5. Test your integration for the callback and flat-rate shipping options.

Post-integration Checkout experience

After you integrate the Instant Update API, you can display the shipping options, related insurance options, and the tax amount. You control what to display, which is instantly updated on the page.

How the callback works in the Express Checkout flow

The Express Checkout flow is initiated on your shopping cart page when the buyer clicks Checkout with PayPal.

From left to right, the diagram shows the following events:

Step Description
1. The buyer clicks Checkout with PayPal on your shopping cart page and initiates the Express Checkout flow.
2. In the SetExpressCheckout call, provide the URL where PayPal can call your callback server, the flat-rate shipping options, and cart line-item details.
3. Get the token from the response.
4. Redirect the buyer's browser to PayPal.
5. When the buyer first logs in to the PayPal site, PayPal obtains the buyer's shipping address and sends it in the callback request, as shown in the red down arrow, to your callback server at the specified URL.
Note: If the buyer changes their shipping address on the PayPal pages during checkout, PayPal makes subsequent requests to the callback server.
6. Your callback server responds with the shipping option rates (shown by the red up arrow) based on the buyer's shipping address. You can also adjust the tax amount and send insurance options. Depending on your business processes, you may send an API call to your carrier to calculate the rates and options based on the shipping address.
7. PayPal updates the cart review area and Review your information page content to show the options and rates based on your response.
8. The buyer makes final selections and clicks Continue.
9. To get the buyer's final shipping option selections, call GetExpressCheckoutDetails.
10. To complete the transaction, call DoExpressCheckoutPayment.

Instant Update API best practices

PayPal recommends these best practices to complete your implementation of the Instant Update API.

Best practice Description
Meet the prerequisites Provide order line-item details to take advantage of the Instant Update API.
Streamline the checkout flow Existing partners and merchants with Express Checkout integrations can eliminate the current shipping options page.
Use the default callback timeout Use the recommended three-second callback response timeout.
Follow PayPal-defined semantics and syntax Adhere to well-formed variable names and syntax rules in the callback response to PayPal. If errors occur in the response, PayPal uses the flat-rate shipping options.
Call GetExpressCheckoutDetails Determine which options the buyer selected.
Ensure a consistent and good buyer experience With flat-rate shipping options, honor the rates to ensure a consistent and correct buyer experience.
Localize shipping options Return localized shipping options, based on the buyer's country and locale, which PayPal sends in the callback request.

Set up the callback

To set up the callback, provide the location where PayPal calls your callback server, along with your shipping options, to establish a connection with PayPal.

To start, you must build and operate a secure, reliable, and fast callback server that computes shipping options, corresponding insurance options, and tax, based on your business rules. To verify that callback requests originate from PayPal.

The HTTP protocol to specify in your callback URL depends on the integration environment you are using:

  • The callback URL must start with HTTPS for production integration.
  • The callback URL must start with HTTP or HTTPS for PayPal sandbox integration.

In the SetExpressCheckout call:

Step Required Description
1. Required Provide line-item details for the merchandise the buyer selected.
2. Required Provide the URL to your callback server, which PayPal validates.
3. Required

Provide values for the flat-rate shipping options. For each option, specify:

  • L_SHIPPINGOPTIONNAMEn. The option name.

  • L_SHIPPINGOPTIONAMOUNTn. The option amount.

  • L_SHIPPINGOPTIONISDEFAULTn. The default shipping option that appears on the PayPal pages. This field is required if you specify the callback URL. Value is:

    • true — The default. PayPal displays this flat-rate shipping option and its amount as the default shipping option.
    • false — PayPal does not display this flat-rate shipping option and its amount as the default shipping option. If you specify false, you can adjust either or both of these values:

      • PAYMENTREQUEST_n_TAXAMT.

      • PAYMENTREQUEST_n_INSURANCEAMT.

    Note: You must specify one and only one default shipping option.
4. Optional To adjust the callback default timeout of three seconds, provide a value from 1 to 6 for the CALLBACKTIMEOUT parameter.
5. Optional You can define these shipping option description details fields:
  • L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMWEITHTUNITm. Option weight.
  • L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm. Option height.
  • L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm, L_PAYMENTREQUEST_n_ITEMLENGTHUNITm. Option length.
  • L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm, L_PAYMENTREQUEST_n_ITEMWIDTHUNITm. Option width.

GetExpressCheckoutDetails and DoExpressCheckoutPayment changes

When you implement the callback, you must call GetExpressCheckoutDetails and DoExpressCheckoutPayment.

GetExpressCheckoutDetails and DoExpressCheckoutPayment include new parameter fields in support of the Instant Update API.

Call GetExpressCheckoutDetails to get the buyer's final shipping option selections. GetExpressCheckoutDetails has been updated to return the buyer's selections.

Because the cart information passed in the SetExpressCheckout call is relevant only for display on the PayPal pages, call DoExpressCheckoutPayment with the updated shipping, insurance, and tax data to ensure the buyer sees it upon redirect to your website.

Other callback considerations

When you implement the callback, you must consider callback response errors, timeouts, and shipping options.

Callback response errors

If there are any callback response errors, PayPal responds by displaying the flat-rate shipping options on the PayPal pages. To obtain the richer set of options available through the callback, exercise care in the syntax and values you specify, and test the callback integration.

Callback timeouts

If the callback does not return within the timeout period, PayPal displays the flat-rate shipping options you specified in the SetExpressCheckout call.

Minimum and maximum shipping options

You can specify up to 10 shipping options for the flat-rate options in the SetExpressCheckout call and for the detailed options based on shipping address in the callback response. You must specify at least one shipping option.

You do not ship to the buyer's shipping address

If you do not ship to the buyer's shipping address that PayPal sends in the callback request, set NO_SHIPPING_OPTION_DETAILS to 1 in the callback response.

Note: The SetExpressCheckout request must set the CALLBACKVERSION to 61.0 or greater.

The following sample code illustrates the callback response when you do not ship to the buyer's address.

METHOD=CallbackResponse
NO_SHIPPING_OPTION_DETAILS =1
CALLBACKVERSION= <61.0 or greater>

When your callback server sends the previous response, the Review your information page has these features:

  • A message at the top of the page indicates that your business does not ship to this location.
  • The shipping and handling section and the insurance section are dimmed.
  • The buyer can change the shipping address.
  • A new callback request is sent if the buyer changes the shipping address.

Use the callback

To use the callback, you add parameter fields to SetExpressCheckout, provide PayPal a URL for sending a callback request, and send PayPal the callback response in Name-Value pair (NVP) format.

SetExpressCheckout

In the SetExpressCheckout call, set these parameters:

  • Set the CALLBACK field to the URL where PayPal can call your callback server. PayPal makes the HTTPS callback request each time either of the following events occur:

    • The buyer changes their shipping address
    • The buyer enters a new shipping address
  • Provide values for the following required parameters:

    • Provide values for the line-item details parameters, such as L_PAYMENTREQUEST_n_NAMEm, L_PAYMENTREQUEST_n_NUMBERm, L_PAYMENTREQUEST_n_DESCm, L_PAYMENTREQUEST_n_AMTm, and L_PAYMENTREQUEST_n_QTYm.

    • Provide values for the flat-rate shipping options: n, L_SHIPPINGOPTIONISDEFAULTn, L_SHIPPINGOPTIONNAMEn, and L_SHIPPINGOPTIONAMOUNTn.

    • Set PAYMENTREQUEST_n_SHIPPINGAMT to the amount set for the default flat-rate shipping option. If, for example, L_SHIPPINGOPTIONISDEFAULT0=true and L_SHIPPINGOPTIONAMOUNT0=8.00, then PAYMENTREQUEST_0_SHIPPINGAMT=8.00.

    • Set MAXAMT to the expected maximum total amount of the complete order.

      Note: PayPal recommends that the maximum total amount be slightly greater than the sum of the line-item order details, tax, and the shipping option of greatest value.

  • Optionally, provide values for the following parameters:

    • Set PAYMENTREQUEST_n_INSURANCEOPTIONOFFERED to true to inform PayPal that you are offering insurance options. Otherwise, set PAYMENTREQUEST_n_INSURANCEOPTIONSOFFERED to false.
    • Set line-item description details, such as L_PAYMENTREQUEST_n_ITEMWEIGHTUNIT0 and L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0, as shown in the following example.
    • Set CALLBACKTIMEOUT to the amount of time in seconds to process the callback. By default, CALLBACKTIMEOUT is 3. You can specify a value in the range of from 1 to 6.

The following is an example SetExpressCheckout request:

Request Parameters

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&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
&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=6230
&L_PAYMENTREQUEST_0_DESC1=Size: Two 24-piece boxes
&L_PAYMENTREQUEST_0_AMT1=39.70
&L_PAYMENTREQUEST_0_QTY1=2
&L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE0=0.5
&L_PAYMENTREQUEST_0_ITEMWEIGHTUNIT0=lbs
&PAYMENTREQUEST_0_ITEMAMT=99.30
&PAYMENTREQUEST_0_TAXAMT=2.59
&MAXAMT=150.00
&PAYMENTREQUEST_0_SHIPPINGAMT=8.00
&PAYMENTREQUEST_0_SHIPDISCAMT=-3.00
&PAYMENTREQUEST_0_AMT=107.89
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&CALLBACK=https://...
&CALLBACKTIMEOUT=4
&PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED=true
&PAYMENTREQUEST_0_INSURANCEAMT=1.00
&L_SHIPPINGOPTIONISDEFAULT0=false
&L_SHIPPINGOPTIONNAME0=UPS Ground 7 Days
&L_SHIPPINGOPTIONAMOUNT0=3.50
&L_SHIPPINGOPTIONISDEFAULT1=true
&L_SHIPPINGOPTIONNAME1=UPS Next Day Air
&L_SHIPPINGOPTIONAMOUNT1=8.00

Response parameters

[successResponseFields]
&TOKEN=EC-17C76533PL706494P

Callback request

The PayPal sends the parameters in the callback request to the location you specified for CALLBACK.

The callback request parameters include:

  • Line-item details you sent in the SetExpressCheckout call. PayPal also sends back any line-item description details you may have specified, such as the L_ITEMWEIGHTUNIT1 and L_ITEMWEIGHTVALUE1 values shown in the following example. By passing this data back to you, PayPal expedites your callback response by eliminating the need for you to complete a database query to obtain this information.
  • Shipping address of the buyer.

Using the information in the callback request, calculate the rates and options yourself or send the information in an API call to your carrier to complete the calculations for you. Then send the shipping options, insurance amounts, and taxes to PayPal in the callback response.

This is an example callback request:

METHOD=CallbackRequest
&CALLBACKVERSION=_XX_.0
&TOKEN=EC-0EE85728D547104V
&CURRENCYCODE=USD
&LOCALECODE=en_US
&L_NAME0=10% Decaf Kona Blend Coffee
&L_NUMBER0=623083
&L_DESC0=Size: 8-oz
&L_AMT0=9.95
&L_QTY0=2
&L_NAME1=Coffee Filter bags
&L_NUMBER1=6230
&L_DESC1=Size: Two 24-piece boxes
&L_AMT1=39.70
&L_QTY1=2
&L_ITEMWEIGHTUNIT1=lbs
&L_ITEMWEIGHTVALUE1=0.5
&SHIPTOSTREET=1 Main St
&SHIPTOCITY=San Jose
&SHIPTOSTATE=CA
&SHIPTOCOUNTRY=US
&SHIPTOZIP=95131
&SHIPTOSTREET2

Callback response

Each time that your callback server receives a request from PayPal, it must process the request and respond with the appropriate details. This is an example callback response:

METHOD=CallbackResponse
&OFFERINSURANCEOPTION=true
&L_SHIPPINGOPTIONNAME0=UPS Next Day Air
&L_SHIPPINGOPTIONAMOUNT0=20.00
&L_TAXAMT0=2.20
&L_INSURANCEAMOUNT0=1.51
&L_SHIPPINGOPTIONISDEFAULT0=false
&L_SHIPPINGOPTIONNAME1=UPS Express 2 Days
&L_SHIPPINGOPTIONAMOUNT1=10.00
&L_TAXAMT1=2.00
&L_INSURANCEAMOUNT1=1.35
&L_SHIPPINGOPTIONISDEFAULT1=true
&L_SHIPPINGOPTIONNAME2=UPS Ground 2 to 7 Days
&L_SHIPPINGOPTIONAMOUNT2=9.99
&L_TAXAMT2=1.99
&L_INSURANCEAMOUNT2=1.28
&L_SHIPPINGOPTIONISDEFAULT2=false
Feedback