Callback API Operation (NVP)

API

Last updated: Aug 15th, 7:29am

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

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. 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.

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.
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: 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: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY 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_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: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY 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 nine (9) digits in SOAP request/response for USD, CLP, or JPY 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