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 pages displayed by PayPal during Express Checkout.

Character length and limitations: Any two-character country code.

The following two-character country codes are supported by PayPal:


  • AU – Australia

  • AT – Austria

  • BE – Belgium

  • BR – Brazil

  • CA – Canada

  • CH – Switzerland

  • CN – China

  • DE – Germany

  • ES – Spain

  • GB – United Kingdom

  • FR – France

  • IT – Italy

  • NL – Netherlands

  • PL – Poland

  • PT – Portugal

  • RU – Russia

  • US – United States

  • The following 5-character codes are also supported for languages in specific countries:


    • da_DK – Danish (for Denmark only)

    • he_IL – Hebrew (all)

    • id_ID – Indonesian (for Indonesia only)

    • ja_JP – Japanese (for Japan only)

    • no_NO – Norwegian (for Norway only)

    • pt_BR – Brazilian Portuguese (for Portugal and Brazil only)

    • ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)

    • sv_SE – Swedish (for Sweden only)

    • th_TH – Thai (for Thailand only)

    • tr_TR – Turkish (for Turkey only)

    • zh_CN – Simplified Chinese (for China only)

    • zh_HK – Traditional Chinese (for Hong Kong only)

    • zh_TW – Traditional Chinese (for Taiwan only)

Any other value will default to US.

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 if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. PayPal accepts State codes for some countries.

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 a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

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 a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

L_INSURANCEAMOUNTn

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

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

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