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
- 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.
- Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
- PayPal displays this information in the cart review area so buyers can choose from the options.
- The buyer's final choices are returned in the
To integrate the Instant Update API, you must modify Express Checkout API calls:
|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:
|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:
|1.||The buyer clicks Checkout with PayPal on your shopping cart page and initiates the Express Checkout flow.|
|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
|10.||To complete the transaction, call
Instant Update API best practices
PayPal recommends these best practices to complete 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 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.
|1.||Required||Provide line-item details for the merchandise the buyer selected.|
|2.||Required||Provide the URL to your callback server, which PayPal validates.|
Provide values for the flat-rate shipping options. For each option, specify:
|4.||Optional||To adjust the callback default timeout of three seconds, provide a value from
|5.||Optional||You can define these shipping option description details fields:
GetExpressCheckoutDetails and DoExpressCheckoutPayment changes
When you implement the callback, you must call
DoExpressCheckoutPayment include new parameter fields in support of the Instant Update API.
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.
If the callback does not return within the timeout period, PayPal displays the flat-rate shipping options you specified in the
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
1 in the callback response.
SetExpressCheckoutrequest must set the
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 call, set these parameters:
CALLBACKfield 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
- Provide values for the flat-rate shipping options: n,
PAYMENTREQUEST_n_SHIPPINGAMTto the amount set for the default flat-rate shipping option. If, for example,
MAXAMTto 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.
- Provide values for the line-item details parameters, such as
Optionally, provide values for the following parameters:
trueto inform PayPal that you are offering insurance options. Otherwise, set
- Set line-item description details, such as
LPAYMENTREQUESTn_ITEMWEIGHTVALUE0, as shown in the following example.
CALLBACKTIMEOUTto the amount of time in seconds to process the callback. By default,
3. You can specify a value in the range of from
The following is an example
[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
The PayPal sends the parameters in the callback request to the location you specified for
The callback request parameters include:
- Line-item details you sent in the
SetExpressCheckoutcall. PayPal also sends back any line-item description details you may have specified, such as the
L_ITEMWEIGHTVALUE1values 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
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