Earlier NVP API versions

You can still use earlier API versions but PayPal recommends that you use the latest vwhenever possible.

What's new in v95.0

Maintenance release. Updated for v95.0. Added new 11800 error field and fulfillmentReferenceNumber field related to Global Shipping Program (GSP). See PayPal Release Notes for more information: Release Notes

What's new in v93.0

Maintenance release. New 10486 error code added for redirects when the process declines the transaction: The transaction couldn't be completed. Please redirect your customer to PayPal.

What's new in v92.0

Updated for v92.0. Added new MsgSubID field for the following APIs for both requests and responses: RefundTransaction, DoReferenceTransaction, DoAuthorization, and DoCapture.

What's new in v91.0

Maintenance release.

What's new in v89.0

Updated for v89.0. Added new field to SetExpressCheckout and DoReferenceTransaction request APIs. Added new error to DoReferenceTransaction request API.

What's new in v88.0

Maintenance release. Updated for v88.0.

What's new in v85.0

No new features added. Maintenance release.

What's new in v84.0

New RefundTransaction response field

Field Description
REFUNDINFO

Contains refund payment status information.

Available since v84.0.

New RefundInfoType in RefundTransaction response

Field Description
REFUNDSTATUS

Status of the refund. Value is:

  • instant
  • delayed

Available since v84.0.

PENDINGREASON

Reason that the payment is delayed. Value is:

  • none — The refund is instant.
  • echeck — The refund is delayed.

Available since v84.0.

New DoReferenceTransactionResponseDetailsType field

Field Description
PAYMENTADVICECODE

Response code from the processor when a recurring transaction is declined. For details on the meanings of these codes, see AVS, CVV2, and payment advice response codes.

New DoDirectPaymentResponse field

Field Description
PAYMENTADVICECODE

Response code from the processor when a recurring transaction is declined. For details on the meanings of these codes, see AVS, CVV2, and payment advice response codes.

Available since v84.0.

What's new in v82.0

New DoCapture request field

Field Description
MERCHANTSTOREDETAILS

(Optional) Information about the merchant store.

Available since v82.0.

New MerchantStoreDetailsType in DoCapture request

Field Description
STOREID

ID of the merchant store. Required for point-of-sale transactions.

Character length and limitations: 50 single-byte characters.

Available since v84.0.

TERMINALID

(Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters.

Available since v82.0.

New RefundTransaction request fields

Field Description
MERCHANTSTOREDETAILS

(Optional) Information about the merchant store.

Available since v82.0.

RETRYUNTIL

(Optional) Maximum time until you must retry the refund.

Note: This field does not apply to point-of-sale transactions.

Available since v82.0.

REFUNDSOURCE

(Optional)Type of PayPal funding source (balance or eCheck) that can be used for auto refund. Value is:

  • any — The merchant does not have a preference. Use any available funding source.
  • default — Use the merchant's preferred funding source, as configured in the merchant's profile.
  • instant — Use the merchant's balance as the funding source.
  • eCheck — The merchant prefers using the eCheck funding source. If the merchant's PayPal balance can cover the refund amount, use the PayPal balance.
Note: This field does not apply to point-of-sale transactions.

Available since v82.0.

REFUNDTYPE

Type of refund you are making. Value is:

  • Full — Full refund (default).
  • Partial — Partial refund.
  • ExternalDispute — External dispute. Available since v82.0.
  • Other — Other type of refund. Available since v82.0.

New MerchantStoreDetailsType in RefundTransaction request

Field Description
STOREID

ID of the merchant store. Required for point-of-sale transactions.

Character length and limitations: 50 single-byte characters.

Available since v84.0.

TERMINALID (Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters.

Available since v82.0.

What's new in v80.0

New PaymentDetailsType fields in DoReferenceTransaction request

Field Description
RECURRING

(Optional) Flag to indicate a recurring transaction. Value is:

  • Any value other than Y — This is not a recurring transaction (default).
  • Y — This is a recurring transaction.
Note: To pass Y in this field, you must have established a billing agreement with the buyer specifying the amount, frequency, and duration of the recurring payment.

What's new in v74.0

New DoExpressCheckoutPayment behavior

By default, the DoExpressCheckoutPayment API operation is idempotent for all API callers. You can call DoExpressCheckoutPayment up to a maximum of 10 times. However, the result in subsequent responses is different from the original response and returns SuccessWithWarning instead of Success. The exceptions are when DoExpressCheckoutPayment generates an error or the token expires.

This functionality only works with v74.0 or later. There is no change to DoExpressCheckoutPayment functionality if you are not updating to the latest vof the API.

If you update to v74.0 or later but want to opt out of this functionality, contact PayPal.

New DoExpressCheckoutPayment error code

Error Code

Short Message

Long Message

Correcting This Error...

13751 Could not retrieve the original successful response. Transaction completed successfully, but could not retrieve the original successful response.

What's new in v72.0

New TaxIdDetailsType structure in SetExpressCheckout request

Field Description
TAXIDTYPE

New field

The buyer's tax ID type. Required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.

TAXID

New field

The buyer's tax ID. Required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte character for individuals and 14 single-byte characters for businesses.

New TaxIdDetailsType structure in GetExpressCheckoutDetails response

Field Description
TAXIDTYPE

New field

The buyer's tax ID type. Required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.

TAXID

New field

The buyer's tax ID. Required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte character for individuals and 14 single-byte characters for businesses.

What's new in v69

New PaymentDetailsItemType structure in CreateRecurringPaymentsProfile request

Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm

New field

Indicates whether the item is digital or physical goods. For digital goods, Required and you must set it to Digital to get the best rates. Value is:

  • Digital
  • Physical

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMCATEGORY0, L_PAYMENTREQUEST_n_ITEMCATEGORY1).

L_PAYMENTREQUEST_n_NAMEm

New field

Item name.Required when you pass a value for ItemCategory.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).

Character length and limitations: 127 single-byte characters

L_PAYMENTREQUEST_n_DESCm

New field

(Optional) Item description.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).

Character length and limitations: 127 single-byte characters

L_PAYMENTREQUEST_n_AMTm

New field

Cost of item. Required when you pass a value for ItemCategory.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.

L_PAYMENTREQUEST_n_NUMBERm

New field

(Optional) Item number.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).

L_PAYMENTREQUEST_n_QTYm

New field

Item quantity. Required when you pass a value for ItemCategory.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_TAXAMTm

New field

(Optional) Item sales tax.

These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, the decimal separator must be a period (.) and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.

Changes to PaymentDetailsItemType in DoReferenceTransaction request

Field Description
L_ITEMCATEGORYn

New field

Indicates whether the item is digital or physical goods. For digital goods, Required and you must set it to Digital to get the best rates. Value is:

  • Digital
  • Physical

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMCATEGORY0, L_ITEMCATEGORY1).

L_NAMEn

Item name. Required when you pass a value for ItemCategory.

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

Character length and limitations: 127 single-byte characters.

L_AMTn

Cost of item. Required when you pass a value for ItemCategory.

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

Note: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, the decimal separator must be a period (.) and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.

L_QTYn

Item quantity. Required when you pass a value for ItemCategory.

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

Character length and limitations: Any positive integer.

What's new in v66

Changes to PaymentDetailsType in SetExpressCheckout and DoExpressCheckoutPayment requests

Field Description

PAYMENTREQUEST_n_ITEMAMT

ITEMAMT (deprecated)

Sum of cost of all items in this order. For digital goods, Required.

Note: PAYMENTREQUEST_n_ITEMAMT is required if you specify L_PAYMENTREQUEST_n_AMTm.

ITEMAMT is deprecated since v63.0. Use PAYMENTREQUEST_n_ITEMAMT instead.

PAYMENTREQUEST_n_PAYMENTACTION

PAYMENTACTION (deprecated)

How you want to obtain payment. When implementing digital goods, Required and you must set it to Sale.

PAYMENTACTION is deprecated since v63.0. Use PAYMENTREQUEST_n_PAYMENTACTION instead.

Changes to PaymentDetailsItemTypein, SetExpressCheckout, and DoExpressCheckoutPayment requests

Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm

New field

Indicates whether the item is digital or physical goods. Available since v65.1. For digital goods Required and you must set it to Digital. Value is:

  • Digital
  • Physical

L_PAYMENTREQUEST_n_NAMEm

L_NAMEn (deprecated)

Item name. For digital goods, Required.

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).

Character length and limitations: 127 single-byte characters.

L_NAMEn is deprecated since v63.0. Use L_PAYMENTREQUEST_n_NAMEm instead.

L_PAYMENTREQUEST_n_DESCm

L_DESCn (deprecated)

Item description. For digital goods, Required.

You can specify up to ten payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).

Character length and limitations: 127 single-byte characters

L_DESCn is deprecated since v63.0. Use L_PAYMENTREQUEST_n_DESCm instead.

L_PAYMENTREQUEST_n_AMTm

L_AMTn (deprecated)

Cost of item. For digital goods, Required.

You can specify up to ten payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).

Note: If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, the decimal separator must be a period (.) and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.

L_AMTn is deprecated since v63.0. Use L_PAYMENTREQUEST_n_AMTm instead.

L_PAYMENTREQUEST_n_QTYm

L_QTYn (deprecated)

Item quantity. For digital goods, Required.

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).

Character length and limitations: Any positive integer.

L_QTYn is deprecated since v63.0. Use L_PAYMENTREQUEST_n_QTYm instead.

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails response

Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm

New field

Indicates whether item is digital or physical goods. For digital goods Required and you must set it to Digital. Value is:

  • Digital
  • Physical

Available since v65.1.