Implementing the Instant Update API

About the Instant Update API

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.

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.

Here is 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

Integrating the Instant Update API requires some preparation and modification to the Express Checkout API calls.

To integrate the server API, follow these steps:

  1. Set up a secure, fast web service to accept HTTP requests from PayPal. On the live site, it needs to be secured by means of SSL.
  2. Enable the callback service to process PayPal requests and return responses.
  3. Modify the existing Express Checkout API calls to accommodate new parameters.
    • Send the callback URL, shipping, insurance, and tax information to PayPal in the call to SetExpressCheckout.
    • Call GetExpressCheckoutDetails to obtain the buyer's final choices for shipping and insurance, if applicable.
    • Call DoExpressCheckoutPayment with 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.

The shipping options, related insurance options, and the tax amount appear on the page, as follows:


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.

Figure 1. Callback integrated into Express Checkout flow


From left to right, the following events are represented:

  1. The Express Checkout flow is initiated on your shopping cart page when the buyer clicks Checkout with PayPal.
  2. In the call to the SetExpressCheckout API operation, you provide the URL where PayPal can call your callback server, the flat-rate shipping options, and cart line-item details.
  3. You retrieve the token from the response.
  4. You 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 (shown as 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 will make 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. You must call GetExpressCheckoutDetails to obtain the buyer's final shipping option selections.
  10. You call DoExpressCheckoutPayment to perform the transaction.

Following Instant Update API Best Practices

PayPal recommends its list of best practices as a checklist for completing your implementation of the Instant Update API.

  • 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 3-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 – You must call GetExpressCheckoutDetails to find out what options the buyer selected.
  • Ensure a consistent and good buyer experience – With flat-rate shipping options, you should 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.

Setting Up the Callback

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

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 call to SetExpressCheckout, you must complete the steps 1 through 3 below. Steps 4 and 5 are optional:

  1. Provide line-item details for the merchandise the buyer selected.
  2. Provide the URL to your callback server, which PayPal validates.
  3. Provide values for the flat-rate shipping options. For each option, specify:
    • Option name (L_SHIPPINGOPTIONNAMEn)
    • Option amount (L_SHIPPINGOPTIONAMOUNTn)
    • The shipping option to appear as the default (true) (L_SHIPPINGOPTIONISDEFAULTn).
      Note: Set L_SHIPPINGOPTIONISDEFAULTn to true (default) for one and only one shipping option. Set L_SHIPPINGOPTIONISDEFAULTn to false for each of the remaining options.
    • If required, an adjusted value for PAYMENTREQUEST_n_TAXAMT
    • If required, an adjusted value PAYMENTREQUEST_n_INSURANCEAMT
  4. If necessary to adjust the callback timeout (default: 3 seconds), provide a value from 1 to 6 for the CALLBACKTIMEOUT parameter.
  5. Optionally, provide values for any of the shipping option description details fields listed below:
    • Option weight (L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMWEITHTUNITm)
    • Option height (L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm)
    • Option length (L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm, L_PAYMENTREQUEST_n_ITEMLENGTHUNITm)
    • Option width (L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm, L_PAYMENTREQUEST_n_ITEMWIDTHUNITm)

GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes

When you implement the callback, you need to call GetExpressCheckoutDetails and DoExpressCheckoutPayment.

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

You must call the GetExpressCheckoutDetails API operation to obtain the buyer's final shipping option selections. GetExpressCheckoutDetails has been updated to return the buyer's selections.

Because the cart information passed in the call to SetExpressCheckout is relevant only for display on the PayPal pages, you must call the DoExpressCheckoutPayment API operation 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 call to SetExpressCheckout.

Minimum and Maximum Shipping Options

You can specify up to 10 shipping options for the flat-rate options in the call to SetExpressCheckout and for the detailed options based on shipping address in the callback response. You must specify at least 1 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 CALLBACKVERSION must have been set to 61.0 or greater in the SetExpressCheckout request.

The sample code below 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.

Using 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 call to SetExpressCheckout, set the following 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 shown in the example below.
    • 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 1 to 6 inclusive.

The following is an example SetExpressCheckout request:

Request Parameters

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=http://...
&CANCELURL=http://...
&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
&ALLOWNOTE=1
&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 call to SetExpressCheckout. 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 example below. By passing this data back to you, PayPal expedites your callback response by eliminating the need for you to perform 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 perform 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 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 Ground2 to 7 Days
&L_SHIPPINGOPTIONAMOUNT2=9.99
&L_TAXAMT2=1.99
&L_INSURANCEAMOUNT2=1.28
&L_SHIPPINGOPTIONISDEFAULT2=false