Troubleshooting NVP/SOAP Errors

Deprecation notice: PayPal's NVP/SOAP APIs are legacy APIs, but PayPal continues to support them. To access the most current features and security:

For new integrations, start with the latest tools.
For existing integrations, visit the upgrade hub.

10207

The merchant can request the customer to update their payment method and try the transaction again. The merchant can show an error to the customer that their payment method may have insufficient funds, then:

Call the SetExpressCheckout API to complete the payment.
Redirect the customer to PayPal.

10409

See 10409.

10410

See 10410.

10411

See 10411.

10412

Configure your profile to block duplicate invoice numbers.
Make sure each InvoiceID is unique for every transaction. Implement a system that generates unique InvoiceIDs automatically to avoid duplication. For PayPal Payments Pro, the parameter you pass depends on the type of API calls you're making:
- For SOAP, use InvoiceID.
- For NVP, use INVNUM.
Check for duplicates. Before processing a transaction, verify the InvoiceID has not been used previously. This can be done by maintaining a record of all Invoice IDs and cross-referencing them before generating a new ID.
Generate a new, unique InvoiceID for the transaction and process the payment again.

10413

See 10413.

10415

See 10415.

10416

See 10416.

10417

Retry with an alternative payment method. Use an alternative payment method in the PayPal wallet, such as a different credit card, bank account, or PayPal balance.
Check payment method details. Ensure that the selected payment method has sufficient funds and that all billing information is correct and up-to-date.
Contact the financial institution. If the bank or financial institution declined the payment method, contact them to understand the reason and resolve any issues.
Update the PayPal account. Ensure that the PayPal account is in good standing and that there are no limitations or holds that could affect the transaction.

10419

See 10419.

10422

Redirect the buyer back to PayPal to select a new payment method. The checkout can be re-initialized after calling the SetExpressCheckout API.

10423

See 10423.

10426

Ensure that the "ItemTotal" amount is the exact sum of the individual item amounts. Double-check to make sure there are no discrepancies.
Ensure that the "ItemTotal" amount is formatted according to PayPal's requirements. Typically, this means using two decimal places in countries that support cents. For example, use 10.00 for ten dollars.
Ensure that the "ItemTotal" amount is consistent with the currency specified in the request. All amounts should be in the same currency.

{
  "METHOD": "DoExpressCheckoutPayment",
  "PAYMENTREQUEST_0_AMT": "30.00",
  "PAYMENTREQUEST_0_CURRENCYCODE": "USD",
  "PAYMENTREQUEST_0_ITEMAMT": "30.00", // ItemTotal amount
  "L_PAYMENTREQUEST_0_NAME0": "Item 1",
  "L_PAYMENTREQUEST_0_AMT0": "10.00",
  "L_PAYMENTREQUEST_0_QTY0": "1",
  "L_PAYMENTREQUEST_0_NAME1": "Item 2",
  "L_PAYMENTREQUEST_0_AMT1": "20.00",
  "L_PAYMENTREQUEST_0_QTY1": "1"
}

10433

Ensure the OrderDescription parameter is no more than 127 single-byte, alphanumeric characters. Do not leave mandatory fields blank.

10442

Ensure the ButtonSource parameter is no more than 32 single-byte, alphanumeric characters. Do not leave mandatory fields blank.

10444

See 10444.

10471

Verify the return URL in the API request. Ensure the domain is publicly accessible and not blocked by firewalls.

10481

See 10481.

10485

See 10485.

10486

Redirect the buyer to PayPal, have the buyer add or choose a different payment method, and then run the transaction again. Call the SetExpressCheckout API to complete the payment, and if the buyer's payment method still does not go through, show the buyer an error.

See Recover from 10486 Error Code.

10606

The merchant needs to ask the customer to reach out to the customer's bank or payment source and determine why they were declined.

The customer can also provide a different payment source for their purchase. If the error code displays after checkout, the merchant can use another method to collect the funds from the customer.

To avoid this issue, the merchant can capture the transaction and re-authorize it when it's time to ship. PayPal recommends not shipping any items until the authorization is captured.

This error is not caused by a technical error with PayPal or your integration.

10609

See 10609.

10610

See 10610.

10620

See 10620.

10621

See 10621.

10623

Capture the order instead of creating multiple authorization requests against the same order.

10727

Make sure that the address1 field is filled out with a valid street address before submitting the transaction. You can add validation checks in the form to ensure that the address1 field is not left blank.
Check the form and the system that captures and transmits the shipping address to ensure that the address1 field is correctly captured and included in the API request.
Add validation logic to the form or system to ensure the address1 field contains valid data before allowing the transaction to proceed. This logic can include checks for non-empty values and proper formatting.
Test the API request to ensure the address1 field is correctly included and formatted in the DoDirectPayment or DoAuthorization API call.

10728

Ensure the city field is filled out with a valid city name before submitting the transaction. You can add validation checks in the form to ensure that the city field is not left blank.
Check the form and the system that captures and transmits the shipping address information to ensure that the city field is correctly captured and included in the API request.
Add validation logic to the form or system to ensure the city field contains valid data before allowing the transaction to proceed. This logic can include checks for non-empty values and proper formatting.
Test the API request to ensure the city field is correctly included and formatted in the DoDirectPayment or DoAuthorization API call.

10730

See 10730.

10736

See 10736.

11452

Contact PayPal support to enable reference transactions. If calling the API on behalf of a different PayPal account, ensure the account receiving payments has permissions enabled. Ensure the API caller account has enabled all required permissions as well.

11547

Contact PayPal support to enable recurring payments. If calling the API on behalf of a different PayPal account, ensure the account receiving payments has permissions enabled. Ensure the API caller account has enabled all required permissions as well.

11601

The merchant account doesn't support address overrides. Collect the correlation_id from the API response and contact PayPal support.

11607

See 11607.

11812

See 11812.

11815

Check your shopping cart settings or your internal code. Make sure it's rounding off the decimal or percentage values correctly.

13113

Surface an error message to the buyer. Ask them to retry the transaction with a payment method other than PayPal.

10412

Configure your profile to block duplicate invoice numbers.
Make sure each InvoiceID is unique for every transaction. Implement a system that generates unique InvoiceIDs automatically to avoid duplication. For PayPal Payments Pro, the parameter you pass depends on the type of API calls you're making:
- For SOAP, use InvoiceID.
- For NVP, use INVNUM.
Check for duplicates. Before processing a transaction, verify the InvoiceID has not been used previously. This can be done by maintaining a record of all Invoice IDs and cross-referencing them before generating a new ID.
Generate a new, unique InvoiceID for the transaction and process the payment again.

10417

Retry with an alternative payment method. Use an alternative payment method in the PayPal wallet, such as a different credit card, bank account, or PayPal balance.
Check payment method details. Ensure that the selected payment method has sufficient funds and that all billing information is correct and up-to-date.
Contact the financial institution. If the bank or financial institution declined the payment method, contact them to understand the reason and resolve any issues.
Update the PayPal account. Ensure that the PayPal account is in good standing and that there are no limitations or holds that could affect the transaction.

10426

Ensure that the "ItemTotal" amount is the exact sum of the individual item amounts. Double-check to make sure there are no discrepancies.
Ensure that the "ItemTotal" amount is formatted according to PayPal's requirements. Typically, this means using two decimal places in countries that support cents. For example, use 10.00 for ten dollars.
Ensure that the "ItemTotal" amount is consistent with the currency specified in the request. All amounts should be in the same currency.

{
  "METHOD": "DoExpressCheckoutPayment",
  "PAYMENTREQUEST_0_AMT": "30.00",
  "PAYMENTREQUEST_0_CURRENCYCODE": "USD",
  "PAYMENTREQUEST_0_ITEMAMT": "30.00", // ItemTotal amount
  "L_PAYMENTREQUEST_0_NAME0": "Item 1",
  "L_PAYMENTREQUEST_0_AMT0": "10.00",
  "L_PAYMENTREQUEST_0_QTY0": "1",
  "L_PAYMENTREQUEST_0_NAME1": "Item 2",
  "L_PAYMENTREQUEST_0_AMT1": "20.00",
  "L_PAYMENTREQUEST_0_QTY1": "1"
}

10606

The merchant needs to ask the customer to reach out to the customer's bank or payment source and determine why they were declined.

The customer can also provide a different payment source for their purchase. If the error code displays after checkout, the merchant can use another method to collect the funds from the customer.

To avoid this issue, the merchant can capture the transaction and re-authorize it when it's time to ship. PayPal recommends not shipping any items until the authorization is captured.

This error is not caused by a technical error with PayPal or your integration.

10727

Make sure that the address1 field is filled out with a valid street address before submitting the transaction. You can add validation checks in the form to ensure that the address1 field is not left blank.
Check the form and the system that captures and transmits the shipping address to ensure that the address1 field is correctly captured and included in the API request.
Add validation logic to the form or system to ensure the address1 field contains valid data before allowing the transaction to proceed. This logic can include checks for non-empty values and proper formatting.
Test the API request to ensure the address1 field is correctly included and formatted in the DoDirectPayment or DoAuthorization API call.

10728

Ensure the city field is filled out with a valid city name before submitting the transaction. You can add validation checks in the form to ensure that the city field is not left blank.
Check the form and the system that captures and transmits the shipping address information to ensure that the city field is correctly captured and included in the API request.
Add validation logic to the form or system to ensure the city field contains valid data before allowing the transaction to proceed. This logic can include checks for non-empty values and proper formatting.
Test the API request to ensure the city field is correctly included and formatted in the DoDirectPayment or DoAuthorization API call.

Troubleshooting NVP/SOAP Errors

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Troubleshooting NVP/SOAP Errors

On this page

On this page