Callback API Operation (NVP)

APILegacyLast updated: October 12th 2021, @ 6:58:00 pm


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

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.
`partial:partials/docs/shared/cl_shiptostate.en-XC`

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: from three to five days, Ground: from five to seven 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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

L_SHIPPINGOPTIONISDEFAULTn

(Required) The default shipping option that appears on the PayPal pages. This field is required if you specify the callback URL. Value is:

  • true — The default. PayPal displays this flat-rate shipping option and its amount as the default shipping option.
  • false — PayPal does not display this flat-rate shipping option and its amount as the default shipping option. If you specify false, you can adjust either or both of these values:
    • PAYMENTREQUEST_n_TAXAMT.

    • PAYMENTREQUEST_n_INSURANCEAMT.

Note: You must specify one and only one default shipping option.

L_TAXAMTn

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

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

L_INSURANCEAMOUNTn

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

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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