About Previous Versions of the API

Previous versions of the API can still be used; however, PayPal recommends using the latest version whenever possible.

What's New in Version 95.0

Maintenance release. Updated for 95.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 Version 93.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 Version 92.0

Updated for 92.0. Added new MsgSubID field for the following APIs for both requests and responsees: RefundTransaction, DoReferenceTransaction, DoAuthorization, and DoCapture.

What's New in Version 91.0

Maintenance release.

What's New in Version 89.0

Updated for 89.0. Added new field to SetExpressCheckout and DoReferenceTransaction Request APIs. Added new error to DoReferenceTransaction Request API.

What's New in Version 88.0

Maintenance release, updated for 88.0.

What's New in Version 85.0

No new features added; solely a maintenance release.

What's New in Version 84.0

New Field in RefundTransaction Response

Table 1.
Field Description
RefundInfo ebl:RefundInfoType
Contains refund payment status information.
This field is available since version 84.0.

New RefundInfoType in RefundTransaction Response

Field Description
RefundStatus xs:PaymentStatusCodeType
Status of the refund. Value is:
  • instant
  • delayed
This field is available since version 84.0.
PendingReason xs:PendingStatusCodeType
Reason that the payment is delayed. Value is:
  • none — The refund is instant.
  • echeck — The refund is delayed.
This field is available since version 84.0.

New Field in DoReferenceTransactionResponseDetailsType

Field Description
PaymentAdviceCode xs:string
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.
This field is available since version 84.0.

New Field in DoDirectPaymentResponse

Field Description
PaymentAdviceCode xs:string
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.
This field is available since version 84.0.

What's New in Version 82.0

New Field in DoCapture Request

Table 2.
Field Description
MerchantStoreDetails ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.

New MerchantStoreDetailsType in DoCapture Request

Field Description
StoreID xs:string
ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters.
This field is available since version 84.0.
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters.
This field is available since version 82.0.

New Fields in RefundTransaction Request

Table 3.
Field Description
MerchantStoreDetails ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
RetryUntil xs:dateTime

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

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

This field is available since version 82.0.

RefundSource ebl:RefundSourceCodeType
(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.

This field is available since version 82.0.

RefundType ebl:RefundPurposeTypeCodeType
Type of refund you are making. Value is:
  • Full — Full refund (default).
  • Partial — Partial refund.
  • ExternalDispute — External dispute. (Value available since version 82.0)
  • Other — Other type of refund. (Value available since version 82.0)

NewMerchantStoreDetailsType in RefundTransaction Request

Field Description
StoreID xs:string
ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters.
This field is available since version 84.0.
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters.
This field is available since version 82.0.

What's New in Version 80.0

New Field in PaymentDetailsType in DoDirectPayment Request

Table 4.
Field Description
Recurring ns:RecurringFlagType
(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.

This field is introduced in version 80.0 of the API.

New Fields in PaymentDetailsType in DoReferenceTransaction Request

Table 5.
Field Description
Recurring ns:RecurringFlagType
(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.

This field is introduced in version 80.0 of the API.

What's New in Version 74.0

New Behavior of DoExpressCheckoutPayment

By default, the DoExpressCheckoutPayment API operation is idempotent for all API callers. You can call DoExpressCheckoutPayment up to a maximum of 10 times and it returns the same result. The exceptions are when DoExpressCheckoutPayment generates an error or the token expires. This functionality only works with version 74.0 or greater. There is no change to DoExpressCheckoutPayment functionality if you are not updating to the latest version of the API. If you update to version 74.0 or higher 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 Version 72.0

Changes to BuyerDetailsType in SetExpressCheckout Request

Table 6. BuyerDetailsType Fields
Field Description
TaxIdDetails ebl:TaxIdDetailsType
Details about the buyer's tax information. This field is required for Brazil and is for Brazil use only.

New TaxIdDetailsType Structure in SetExpressCheckout Request

Table 7. TaxIdDetailsType Fields
Field Description
TaxIdType New field
xs:string
The buyer's tax ID type. This field is 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
xs:string
The buyer's tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses.

New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response

Table 8. TaxIdDetailsType Fields
Field Description
TaxIdType New field
xs:string
The buyer's tax ID type. This field is 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
xs:string
The buyer's tax ID. This field is 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 Version 69

New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request

Table 9. PaymentDetailsItemType Fields
Field Description
ItemCategory New field
ns:ItemCategoryType
Indicates whether the item is digital or physical goods. For digital goods, this field is required and you must set it to Digital to get the best rates. Value is:
  • Digital
  • Physical
Name New field
xs:string
Item name.This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters.
Description New field
xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters.
Amount New field
ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.

Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

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.

Number New field
xs:string
(Optional) Item number.
Quantity New field
xs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
Character length and limitations: Any positive integer
Tax New field
ebl:BasicAmountType
(Optional) Item sales tax.

Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

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

Table 10. PaymentDetailsItemType Fields
Field Description
ItemCategory New field
ns:ItemCategoryType
Indicates whether the item is digital or physical goods. For digital goods, this field is required and you must set it to Digital to get the best rates. Value is:
  • Digital
  • Physical
Name xs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters.
Amount ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.

Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

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.

Quantity xs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
Character length and limitations: Any positive integer.

What's New in Version 66

Changes to PaymentDetailsType in SetExpressCheckout and DoExpressCheckoutPayment Requests

Table 11. PaymentDetailsType Fields
Field Description
ItemTotal ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.

Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.
PaymentAction ebl:PaymentActionCodeType
How you want to obtain payment. When implementing digital goods, this field is required and you must set it to Sale.

Changes to PaymentDetailsItemTypein SetExpressCheckout and DoExpressCheckoutPayment Requests

Table 12. PaymentDetailsItemType Fields
Field Description
ItemCategory ns:ItemCategoryType
New field
Indicates whether the item is digital or physical goods. This field is available since version 65.1. For digital goods this field is required and you must set it to Digital. Value is:
  • Digital
  • Physical
Name xs:string
Item name. For digital goods, this field is required.
Character length and limitations: 127 single-byte characters.
L_NAMEn is deprecated since version 63.0. Use L_PAYMENTREQUEST_n_NAMEm instead.
Description xs:string
Item description. For digital goods, this field is required.
Character length and limitations: 127 single-byte characters.
Amount ebl:BasicAmountType
Cost of item. For digital goods, this field is required.

Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

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.

Quantity xs:integer
Item quantity. For digital goods, this field is required.
Character length and limitations: Any positive integer.

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response

Field Description
ItemCategory ns:ItemCategoryType
New field
Inicates whethe item is digital or physical goods. For digital goods this field is required and you must set it to Digital. Value is:
  • Digital
  • Physical
This field is available since version 65.1.