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.

The buyer must restart the checkout process to create a new checkout session with a new token that the buyer must approve. Do not reuse the expired token value in the SetExpressCheckout request. If you know the final OrderTotal, update the value for that element. You can also update the values for ReturnURL and CancelURL if necessary.

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

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.

1. Ensure you follow the correct API call sequence:
   1. SetExpressCheckout
   2. GetExpressCheckoutDetails
   3. DoExpressCheckoutPayment
2. Ensure you retrieve the Payer ID from the GetExpressCheckoutDetails API call response.
3. Ensure the PAYERID parameter is in the DoExpressCheckoutPayment API call.
4. Ensure the Payer ID is correctly stored and passed between API calls with no issues with session management or data handling.

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

1. Use the same PaymentAction for the DoExpressCheckout API call you used in the initial SetExpressCheckout API call.
2. Grant the third-party permissions required to complete the API call on your behalf.
3. Ensure your PayPal business account is verified with a confirmed email address.

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.

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

• Notify customers about the error and provide guidance on how to resolve it.
• Retry Express Checkout. Implement a mechanism to redirect the customer back to PayPal to retry the payment. Use the token value returned from SetExpressCheckout to redirect the customer to a PayPal log-in page. After the customer logs in, PayPal displays the transaction details on the payments review page, where the customer needs to approve the payment.

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.

• Ensure the postal code field is filled out with a valid five-digit ZIP code before submitting the transaction. You can add validation checks in the form to ensure that the postal code field is not left blank and is in the correct format.
• Check the form and the system that captures and transmits the shipping address information to ensure that the postal code field is captured and included in the API request.
• Add validation logic to the form or system to ensure the postal code field contains valid data before allowing the transaction to proceed. This logic can include checks for non-empty values, proper formatting, and ensuring that the postal code consists of five numeric digits.

An issue occurred with the address field. The error message specifies which field is incorrect.

Redirect the buyer to the shipping information page so they can update their address.

Note: The optional ADDROVERRIDE field controls how PayPal displays the shipping address:

• 0 – The PayPal checkout page does not display the shipping address.
• 1 – The PayPal checkout page displays the shipping address provided in the SetExpressCheckout request, instead of the buyer's saved PayPal address.

If the buyer’s saved PayPal address is displayed, the buyer cannot edit it.

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.

• If this request is for a payment that was processed prior, then no action is required. 
• If this is a new transaction request, submit a new request with a different MSGSUBID or INVOICE_ID.
• Ensure the merchant is subscribed to Instant Payment Notifications or Webhooks so that even if they miss the API response initially, they can sync up their systems with the latest payment status within PayPal and avoid duplicate transaction requests.

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.