Implementing the Instant Update API
The Instant Update API is a callback you can use to obtain the buyer's shipping address.
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:
- 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
Integrating the Instant Update API requires some preparation and modification to the Express Checkout API calls.
To integrate the server API, follow these steps:
- 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.
- Enable the callback service to process PayPal requests and return responses.
- Modify the existing Express Checkout API calls to accommodate
- Send the callback URL, shipping, insurance,
and tax information to PayPal in the call to
GetExpressCheckoutDetailsto obtain the buyer's final choices for shipping and insurance, if applicable.
DoExpressCheckoutPaymentwith the buyer's final selections.
- Send the callback URL, shipping, insurance, and tax information to PayPal in the call to
- Eliminate your shipping options page.
- Test your integration for the callback and flat-rate shipping options.
Post-Integration Checkout Experience
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 following events are represented:
- The Express Checkout flow is initiated on your shopping cart page when the buyer clicks Checkout with PayPal.
- In the call to the
SetExpressCheckoutAPI operation, you provide the URL where PayPal can call your callback server, the flat-rate shipping options, and cart line-item details.
- You retrieve the token from the response.
- You redirect the buyer's browser to PayPal.
- 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
Note: If the buyer changes their shipping address on the PayPal pages during checkout, PayPal will make subsequent requests to the callback server.
- 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.
- PayPal updates the cart review area and Review your information page content to show the options and rates based on your response.
- The buyer makes final selections and clicks Continue.
- You must call
GetExpressCheckoutDetailsto obtain the buyer's final shipping option selections.
- You call
DoExpressCheckoutPaymentto 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
GetExpressCheckoutDetailsto 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
you must complete the steps 1 through 3 below. Steps 4 and 5 are
- Provide line-item details for the merchandise the buyer selected.
- Provide the URL to your callback server, which PayPal validates.
Provide values for the flat-rate shipping options. For
each option, specify:
- Option name (
- Option amount (
- The shipping option to appear as the default (
true(default) for one and only one shipping option. Set
falsefor each of the remaining options.
- If required, an adjusted value for
- If required, an adjusted value
- Option name (
- If necessary to adjust the callback timeout (default:
3 seconds), provide a value from
Optionally, provide values for any of the shipping option
description details fields listed below:
- Option weight (
- Option height (
- Option length (
- Option width (
- Option weight (
GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes
When you implement the callback, you need to call
new parameter fields in support of the Instant Update API.
You must call the
operation to obtain the buyer's final shipping option selections.
been updated to return the buyer's selections.
Because the cart information passed in the call to
relevant only for display on the PayPal pages, you must call the
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.
the callback does not return within the timeout period, PayPal displays
the flat-rate shipping options you specified in the call to
Minimum and Maximum Shipping Options
You can specify up to 10 shipping options
for the flat-rate options in the call to
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
the callback response.
CALLBACKVERSIONmust have been set to
61.0or greater in the
The sample code below illustrates the callback response when you do not ship to the buyer's address.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
provide PayPal a URL for sending a callback request, and send PayPal
the callback response in Name-Value pair (NVP) format.
the call to
SetExpressCheckout, set the following
- Set the
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
- 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
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0shown in the example below.
CALLBACKTIMEOUTto the amount of time in seconds to process the callback. By default,
3. You can specify a value in the range of
following is an example
[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.00Response Parameters
PayPal sends the parameters in the callback request to the location
you specified for
CALLBACK. The callback request
- 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_ITEMWEIGHTVALUE1values 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
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