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.

1. Ensure the token you are using is correct and has not expired. Generate a new token by making a new SetExpressCheckout API call.
2. Ensure the token hasn't been used previously.
3. Double-check the transaction ID to ensure it is correct and corresponds to a transaction.
4. Ensure your API calls are correctly formatted and include all required parameters.

Verify the correct value for the token and resubmit your API call. TOKEN is a time-stamped unit returned in the SetExpressCheckout API response.

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.

Be sure that the total of the payment detail item parameters, such as ItemTotal, HandlingTotal, and TaxTotal add up to the OrderTotal. Check for any updates or modifications that could affect the calculation and ensure the total amount specified in the API request accurately reflects the sum of item amounts, tax, shipping, and other charges.

See 10415.

Implement a mechanism to generate a new token for the customer. You can redirect the customer to the initial checkout page to start the process again. If the transaction fails, do not retry the DoExpressCheckout API call.

• 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 127 or fewer single-byte, alphanumeric characters. Do not leave mandatory fields blank.

Ensure the ButtonSource parameter is 32 or fewer 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 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.

Check whether the authorization ID is valid or expired and reattempt the request. The buyer must start a new transaction or the merchant needs to re-authorize before attempting to capture the payment.

Retry the request again with a higher or lower amount. Check the amount passed in the initial SetExpressCheckout API request and verify whether the same amount is being passed during capture.

1. Determine the status of an order using the order ID and the GetTransactionDetails API.
2. Create a new authorization with the SetExpressCheckout API, then redirect the buyer for approval with their payment method.
3. After the buyer approves, the merchant can capture the payment amount.

1. Determine the status of an order using the order ID and the GetTransactionDetails API.
2. Create a new authorization with the SetExpressCheckout API, then redirect the buyer for approval with their payment method.
3. After the buyer approves, the merchant can capture the payment amount.

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.

Review the API response for details about which argument in the API request was invalid. Upon fixing the invalid argument, the payment should go through. Ensure the description field has no more than 127 characters.

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.