Unprocessable entity

The requested action could not be performed, is semantically incorrect, or failed business validation. The following issues may return from an UNPROCESSABLE_ENTITY error.

Note: If an issue persists or if you have further questions, you can reach out to paypal-techsupport.com.

DUPLICATE_INVOICE_ID

Returns from the Payments v1 or Orders v2 APIs.

CauseImpactResolution
The PayPal REST API generates this error when it detects a duplicate invoice ID. Each transaction must have a unique invoice_id to prevent duplicate transactions. Typically, the invoice_id corresponds to the order_id on the merchant's side. In this scenario, the same order_id is likely reused for a different or new transaction call to PayPal. The invoice_id is a unique field within PayPal's system. The payment process is halted, preventing the buyer from finalizing their purchase. This can lead to lost sales if the issue is not resolved promptly.
  • Send a different value in the invoice_id field.
  • If it is necessary to use the same invoice_id and this error occurs repeatedly, contact PayPal support to allow a duplicate invoice_id.
  • Implement Instant Payment Notifications (IPNs) or webhooks for captures to provide real-time information, helping to avoid sending duplicate capture calls and ensuring smoother transaction processing.

ORDER_ALREADY_AUTHORIZED

Returns from the Payments v2 or Orders v2 APIs.

CauseImpactResolution
  • The PayPal order_id has already been authorized through an API request.
  • If the order was created with intent="AUTHORIZE", only one authorization is allowed per order. A second authorization will be declined with this error code.
  • The merchant may have made a duplicate request or call that failed because the original call succeeded and has already blocked funds on the customer’s PayPal account.
  • The merchant may have missed reading the successful API response from the original authorization call due to network issues or system latencies.
  • There is no impact on the original authorization. This is a decline on a second attempt at authorizing the same PayPal order.
  • A merchant cannot authorize a partial amount of an order and authorize the remainder separately. In that situation, the merchant must create a new PayPal order or realize a loss in sales.
  • Authorize the full order amount in a single request, then create multiple captures instead of multiple authorizations.
  • Create multiple captures by setting final_capture="false" in the capture API requests. This allows for cases such as a split shipment when captures occur at different times based on inventory availability.
  • If the API call was made because the merchant’s systems weren’t updated with the latest order status in PayPal, the merchant may want to integrate PayPal webhooks. Webhooks are instant HTTP POST requests from PayPal to the merchant servers, allowing them to automatically receive and update the latest PayPal order status.
  • If the API calls take too long and cause PayPal responses to time out on the merchant end, contact PayPal technical support.

ORDER_ALREADY_CAPTURED

Returns from the Orders v2 API.

CauseImpactResolution
  • The PayPal order is already in the “captured” state: The payment is complete, and funds have settled into the merchant’s PayPal account. No new captures can be created on the given order.
  • Single capture per order: If you’re creating PayPal orders with intent="SALE", only one capture is allowed per PayPal order.
  • Duplicate request due to missing API response record: The merchant did not record an API success response on the initial capture call and made the same request again. Upon seeing the initial request go through, PayPal rejects the request as a duplicate.
  • If the merchant has captured only a partial amount of the total order, they will not be able to capture the remaining amount unless they create a new PayPal order.
  • No buyer impact if the original intent was to have a single (partial or full) capture on the order. However, there's likely a sync issue between merchant records and the latest PayPal order statuses, resulting in a redundant capture API call.
  • If you want to create multiple captures, use intent="AUTHORIZE", not intent="SALE". With intent="AUTHORIZE", an authorization is created first on the PayPal order. Then, one or more captures can be created on the authorization. Ensure that the final_capture parameter in the capture authorized payment API call is set as false to accommodate further capture API calls. You'll also need to provide a unique invoice_id for each capture.
  • If you want to create a single-shot capture, that's already happened. Ensure the API response (success or decline) is recorded in the database to avoid duplicate API calls.
  • You may want to subscribe to PayPal webhooks that are HTTP POST requests to inform merchant servers about payment status changes.

ORDER_NOT_APPROVED

Returns from the Payments v1 or Orders v2 APIs.

CauseImpactResolution
  • Incomplete checkout process: The buyer may have initiated the checkout process but did not complete the approval step required by PayPal.
  • Missing payment source: The request may not include a valid payment_source, which is required for the order approval.
 The payment is declined, and the payment is not processed. This can lead to delays in completing the purchase.
  • Redirect to approval URL: Ensure that the buyer is redirected to the 'rel':'approve' URL returned as part of the HATEOAS links within the Create Order call. This URL directs the buyer to the PayPal checkout flow to approve the order.
  • Include valid payment source: Ensure that the request includes a valid payment_source.

SHIPPING_ADDRESS_INVALID

Returns from the Payments v1 or Orders v2 APIs.

CauseImpactResolution
  • Incomplete form submission: The buyer may have left out critical address fields, such as a street address, city, or state, when entering their shipping information.
  • Validation issues: The address may be provided in an incorrect format, such as including special characters or not following the standard address format for the destination country.
  • System integration issues: The merchant's system may not be correctly capturing or transmitting the complete address information in the API request to the shipping carrier.
 The payment is declined, and the payment is not processed. This can lead to delays in completing the purchase.
  • Ensure complete address submission: Implement form validation to ensure that all required address fields are filled out correctly before allowing the transaction to proceed. This can include checks for non-empty values and proper formatting.
  • Standardize address format: Use address validation and standardization tools to ensure that the address follows the correct format for the destination country. This can help automatically correct common formatting errors.
  • Review system integration: Check the system that captures and transmits the shipping address information to ensure that all address fields are correctly captured and included in the API request.