About Previous Versions of the API

Previous versions of the API can still be used; however, PayPal recommends using the latest version whenever possible. Unless specifically specified, API operations default to the latest version.

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

Back to top

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.

Back to top

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.

Back to top

What's New in Version 91.0

Maintenance release.

Back to top

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.

Back to top

What's New in Version 88.0

Maintenance release, updated for 88.0.

Back to top

What's New in Version 85.0

No new features added; solely a maintenance release.

Back to top

What's New in Version 84.0

New Field in RefundTransaction Response

Table 1.
Field Description
REFUNDINFO Contains refund payment status information.

This field is available since version 84.0.

New RefundInfoType in RefundTransaction Response

Field Description
REFUNDSTATUS Status of the refund. It is one of the following values:
  • instant
  • delayed
This field is available since version 84.0.
PENDINGREASON Reason that the payment is delayed. It is one of the following values:
  • 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 Response code from the processor when a recurring transaction is declined. For details on the meanings of the codes, see:

https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_codes

This field is available since version 84.0.

New Field in DoDirectPaymentResponse

Field Description
PAYMENTADVICECODE Response code from the processor when a recurring transaction is declined. For details on the meanings of the codes, see: https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_codes

This field is available since version 84.0.

Back to top

What's New in Version 82.0

New Field in DoCapture Request

Table 2.
Field Description
MERCHANTSTOREDETAILS (Optional) Information about the merchant store.

This field is available since version 82.0.

New MerchantStoreDetailsType in DoCapture Request

Field Description
STOREID 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 (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 (Optional) Information about the merchant store.

This field is available since version 82.0.

RETRYUNTIL (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 (Optional)Type of PayPal funding source (balance or eCheck) that can be used for auto refund. It is one of the following values:
  • 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 Type of refund you are making. It is one of the following values:
  • 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)

New MerchantStoreDetailsType in RefundTransaction Request

Field Description
STOREID 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 (Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters

This field is available since version 82.0.

Back to top

What's New in Version 80.0

New Fields in PaymentDetailsType in DoReferenceTransaction Request

Table 4.
Field Description
RECURRING (Optional) Flag to indicate a recurring transaction. It is one of the following values:
  • 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.

Back to top

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. However, the result in subsequent responses will be different from the original response and will return SuccessWithWarning instead of Success. 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.

Back to top

What's New in Version 72.0

New TaxIdDetailsType Structure in SetExpressCheckout Request

Table 5. TaxIdDetailsType Fields
Field Description
TAXIDTYPE New field

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

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.

New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response

Table 6. TaxIdDetailsType Fields
Field Description
TAXIDTYPE New field

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

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.

Back to top

What's New in Version 69

New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request

Table 7. PaymentDetailsItemType Fields
Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm New field

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. It is one of the following values:

  • 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.This field is 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. This field is 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. This field is 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, 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 8. PaymentDetailsItemType Fields
Field Description
L_ITEMCATEGORYn New field

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. It is one of the following values:

  • Digital
  • Physical
These parameters must be ordered sequentially beginning with 0 (for example L_ITEMCATEGORY0, L_ITEMCATEGORY1).
L_NAMEn Item name. This field is 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. This field is 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, 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. This field is 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

Back to top

What's New in Version 66

Changes to PaymentDetailsType in SetExpressCheckout and DoExpressCheckoutPayment Requests

Table 9. PaymentDetailsType Fields
Field Description
PAYMENTREQUEST_n_ITEMAMT

ITEMAMT (deprecated)

Sum of cost of all items in this order. For digital goods, this field is required.
Note:

PAYMENTREQUEST_n_ITEMAMT is required if you specify L_PAYMENTREQUEST_n_AMTm.

ITEMAMT is deprecated since version 63.0. Use PAYMENTREQUEST_n_ITEMAMT instead.

PAYMENTREQUEST_n_PAYMENTACTION

PAYMENTACTION (deprecated)

How you want to obtain payment. When implementing digital goods, this field is required and you must set it to Sale.

PAYMENTACTION is deprecated since version 63.0. Use PAYMENTREQUEST_n_PAYMENTACTION instead.

Changes to PaymentDetailsItemTypein SetExpressCheckout and DoExpressCheckoutPayment Requests

Table 10. PaymentDetailsItemType Fields
Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm 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. It is one of the following values:

  • Digital
  • Physical
L_PAYMENTREQUEST_n_NAMEm

L_NAMEn (deprecated)

Item name. For digital goods, this field is 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 version 63.0. Use L_PAYMENTREQUEST_n_NAMEm instead.

L_PAYMENTREQUEST_n_DESCm

L_DESCn (deprecated)

Item description. For digital goods, this field is 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_DESC0, L_PAYMENTREQUEST_n_DESC1).

Character length and limitations: 127 single-byte characters

L_DESCn is deprecated since version 63.0. Use L_PAYMENTREQUEST_n_DESCm instead.

L_PAYMENTREQUEST_n_AMTm

L_AMTn (deprecated)

Cost of item. For digital goods, this field is 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_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, 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 version 63.0. Use L_PAYMENTREQUEST_n_AMTm instead.

L_PAYMENTREQUEST_n_QTYm

L_QTYn (deprecated)

Item quantity. For digital goods, this field is 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 version 63.0. Use L_PAYMENTREQUEST_n_QTYm instead.

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response

Field Description
L_PAYMENTREQUEST_n_ITEMCATEGORYm New field

Inicates whethe item is digital or physical goods. For digital goods this field is required and you must set it to Digital. It is one of the following values:

  • Digital
  • Physical
This field is available since version 65.1.

Back to top