Callback API Operation (NVP)

Updates the PayPal Review page with shipping options, insurance, and tax information.

Callback API Request Message

Callback Request Fields

Field Description

METHOD

(Required) Must be Callback.

TOKEN

(Optional) A timestamped token, the value of which was returned by SetExpressCheckout response.

Character length and limitations: 20 single-byte characters

CURRENCYCODE

(Required) The three-character currency code for the transaction from the Express Checkout API. Default: USD

LOCALECODE

(Optional) Locale of the pages displayed by PayPal during Express Checkout. It is either a two-letter country code or five-character locale code supported by PayPal.

Note: If the locale code is not supplied or the supplied value is not one of the listed values, it is defaulted by PayPal. The default is determined using information about the current merchant, user, and other information for the session.

Character length and limitations: A two-letter country code or five-character locale code supported by PayPal.

L_NAMEn

Item name from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_NAME0, L_NAME1).

L_NUMBERn

Item number from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_NUMBER0, L_NUMBER1).

L_DESCn

Item description from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_DESC0, L_DESC1).

L_AMTn

Item unit price from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_AMT0, L_AMT1).

L_QTYn

Item unit quantity from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_QTY0, L_QTY1).

L_ITEMWEIGHTVALUEn L_ITEMWEIGHTUNITn

The weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

L_ITEMHEIGHTVALUEn L_ITEMHEIGHTUNITn

The height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1).

L_ITEMWIDTHVALUEn L_ITEMWIDTHUNITn

The width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

L_ITEMLENGTHVALUEn L_ITEMLENGTHUNITn

The length of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, ITEMLENGTHVALUE0, ITEMLENGTHVALUE1).

SHIPTOSTREET

First street address. Required if using a shipping address.

Character length and limitations: 300 single-byte characters.

SHIPTOSTREET2

Second street address.

Character length and limitations: 300 single-byte characters.

SHIPTOCITY

Name of city. Required if using a shipping address.

Character length and limitations: 40 single-byte characters.

SHIPTOSTATE

State or province.

It is required for transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. See the list of PayPal State codes.

Character length and limitations: 40 single-byte characters.

SHIPTOZIP

U.S. ZIP code or other country-specific postal code. Required if using a U.S. shipping address; may be required for other countries.

Character length and limitations: 20 single-byte characters.

SHIPTOCOUNTRY

Country code. Required if using a shipping address.

Character limit: 2 single-byte characters.

Callback Response Message

Callback Response Fields

Field Description

METHOD

(Required) The method sent to the PayPal server. The value is always CallbackResponse.

CURRENCYCODE

(Required) The three-character currency code for the transaction from the Express Checkout API.

OFFERINSURANCEOPTION

(Optional) Indicates whether or not PayPal should display insurance in a drop-down list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string 'Yes.'

L_SHIPPINGOPTIONNAMEn

(Required) Is the internal/system name of a shipping option, such as Air, Ground, or Expedited.

These parameters must be ordered sequentially beginning with 0 (for example, L_SHIPPINGOPTIONNAME0, L_SHIPPINGOPTIONNAME1).

Character length and limitations: 50 characters

L_SHIPPINGOPTIONLABELn

(Required) The label for the shipping option as displayed to the buyer. Examples: Air: Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized based on the buyer's locale, which is a part of the callback request.

These parameters must be ordered sequentially beginning with 0 (for example, L_SHIPPINGALABEL0, L_SHIPPINGLABEL1).

Character length and limitations: 50 characters

L_SHIPPINGOPTIONAMOUNTn

(Required) Is the amount for this shipping option.

These parameters must be ordered sequentially beginning with 0 (for example, L_SHIPPINGAMOUNT0, L_SHIPPINGAMOUNT1).

Character length and limitation:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

L_SHIPPINGOPTIONISDEFAULT

(Required) The option that is selected by default for the buyer and is also reflected in the "default" total.

L_TAXAMTn

(Optional) New tax amount based on this shipping option and the shipping address.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

L_INSURANCEAMOUNTn

(Optional) New insurance amount based on this shipping option and the shipping address.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

OFFERINSURANCEOPTION

(Optional) Indicates whether or not PayPal should display insurance in a drop-down list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string 'Yes.'

NO_SHIPPING_OPTION_DETAILS

(Optional) If you do not ship to the buyer's shipping address, set this field to 1. The value of CALLBACKVERSION in SetExpressCheckout request must be 61.0 or greater, similar to the following:

CALLBACKVERSION=<61.0 or greater>

Character length and limitations: string