Troubleshooting NVP/SOAP Errors

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:

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

See 10409.

See 10410.

See 10411.

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

See 10413.

See 10415.

See 10416.

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

See 10419.

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

See 10423.

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

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

See 10444.

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

See 10481.

See 10485.

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.

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.

See 10609.

See 10610.

See 10620.

See 10621.

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

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

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

See 10730.

See 10736.

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.

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.

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

See 11607.

See 11812.

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

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