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.

CARD_EXPIRED

Returns from the PayPal Orders v2 or Payments v1 APIs.

Cause	This error occurs when a PayPal payment attempt fails due to an expired card. An expired card is no longer valid for transactions. The buyer must use a different card or select an alternative payment method to complete the payment.
Impact	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.
Resolution	Display the error message to the buyer, indicating that the card used is expired. Guide the buyer to enter a different card through PayPal or the PayPal Commerce Platform to complete the purchase. Help the buyer switch payment methods and continue with the transaction through simple, clear instructions.

DUPLICATE_INVOICE_ID

Returns from the Payments v1 or Orders v2 APIs.

Cause	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.
Impact	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.
Resolution	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.

Cause	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.
Impact	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.
Resolution	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.

Cause	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.
Impact	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.
Resolution	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.

Cause	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.
Impact	The payment is declined, and the payment is not processed. This can lead to delays in completing the purchase.
Resolution	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`.

PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING

Returns from the Orders v2 API.

Cause	The API returns this error when the payee's account is not set up to receive card payments. The payment is not processed and will not go through until card payments are enabled on the payee's account. This error may also show up if the payee has not been fully onboarded to accept payments with PayPal Complete Payments.
Impact	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. The error affects all customers who attempt to send payments to this specific payee, not just a single customer.
Resolution	Make sure the payee has completed onboarding correctly. If you are using the PayPal Complete Payments platform, ask the payee to go through the onboarding process again and confirm that card payments are included. If the issue persists, contact PayPal support. If the payee manages their own onboarding, ask them to contact PayPal directly to enable card payments on their account.

REDIRECT_PAYER_FOR_ALTERNATE_FUNDING

Returns from the Payments v1 or Orders v2 APIs.

Cause	The API returns this error when a PayPal payment fails due to an issue with the payment method the buyer selected in their PayPal wallet.
Impact	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.
Resolution	Display the error message to the buyer, explaining that the payment did not go through and that they need to try a different payment method within their wallet. Redirect the buyer to PayPal checkout so they can choose another payment source. If the issue persists, ask the buyer to use a different payment method, such as a credit card. If the issue still persists, suggest that the buyer contact PayPal to resolve any issues with their PayPal wallet. Use clear instructions to help the buyer complete the payment and reduce friction during checkout.

REFERENCED_CARD_EXPIRED

Returns from the Orders v2 or Vault v3 APIs.

Cause	The API returns this error when a transaction is attempted using a saved payment method token, but the card linked to the token is expired. As a result, the transaction fails. The buyer must use a different card or choose another payment method to continue.
Impact	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.
Resolution	Enable Real-Time Account Updater (RTAU): If you use PayPal Complete Payments with advanced credit and debit cards, enable Real-Time Account Updater on your vault integration. This feature syncs with card issuers and automatically updates saved cards with new expiration dates when cards are renewed. RTAU for direct merchants RTAU for multiparty Display the error message: Let the buyer know their saved card has expired. Update the saved payment token: After you receive a new payment token, update it in your database and remove the old token linked to the expired card from the PayPal vault and your system. Use clear instructions to help the buyer complete the payment and reduce the risk of dropped transactions.

SHIPPING_ADDRESS_INVALID

Returns from the Payments v1 or Orders v2 APIs.

Cause	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.
Impact	The payment is declined, and the payment is not processed. This can lead to delays in completing the purchase.
Resolution	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.

TOKEN_ID_NOT_FOUND

Returns from the Payments v1 or Orders v2 APIs.

Cause	This error occurs when PayPal does not recognize the token ID in the API request. Possible causes include an invalid or mistyped token. It can also occur if the API caller does not have the required permissions from the receiver's account to use the token.
Impact	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.
Resolution	Check permissions: If one PayPal account calls an API on behalf of another, ensure the receiving account has granted the necessary permissions to the caller. Permissions can be granted using the PayPal Permissions API or manually through the account settings. Review your code: Ensure the token ID is not altered or modified before the API call. Reissue token: If the token is invalid or expired, generate a new token and use it in the API request.