Understanding Error: Unprocessable entity

When your payment request cannot be completed due to incorrect information or business rule violations. The following issues might return an UNPROCESSABLE_ENTITY error.

• Expired Card
• Duplicate Invoice ID
• Order Already Authorized
• Order Already Captured
• Order Not Approved
• Redirect Payer for Alternate Funding
• Referenced Card Expired
• Shipping Address Invalid
• Token ID Not Found

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

Expired Card

Returns from the PayPal Orders v2 or Payments v1 APIs. Refer to the Card Expired developer document.

Cause
This error happens when a customer tries to pay with a credit or debit card that has passed its expiration date. An expired card cannot be used for any purchases.

Impact
The payment stops immediately, and your customer cannot complete their purchase. If not addressed quickly, you might lose the sale.

Resolution

• Show the customer a message explaining that their card has expired.
• Help them enter a different card through PayPal or the PayPal Commerce Platform.
• Provide simple instructions for switching to another payment method to complete their purchase.

Duplicate Invoice ID

Returns from the Payments v1 or Orders v2 APIs. Refer to the Duplicate Invoice ID developer document.

Cause
PayPal detects a duplicate invoice ID. Each transaction needs a unique invoice_id to prevent duplicate transactions. This typically happens when the same order number is used for multiple transactions.

Impact
The payment process stops, preventing your customer from completing their purchase. This can lead to lost sales.

Resolution
Use a different invoice ID number for each transaction. If you need to use the same invoice ID repeatedly, contact PayPal support. Consider setting up Instant Payment Notifications (IPNs) or webhooks to get real-time updates about transactions.

Order Already Authorized

Returns from the Payments v2 or Orders v2 APIs. Refer to the Order Already Authorized developer document.

Cause
The order has already been authorized through a previous request. When an order is created with intent="AUTHORIZE", only one authorization is allowed. A second attempt will be declined. This might happen if you accidentally sent the same request twice, or if you missed seeing that the first request was successful.

Impact
There's no impact on the original authorization. Only the second attempt is declined. You cannot authorize a partial amount now and authorize the remainder later.

Resolution
Authorize the full amount in one request, then create multiple captures as needed. Create multiple captures by setting final_capture="false" in your capture requests. This is useful for split shipments. Consider integrating PayPal webhooks to automatically receive updates about order status. If API calls are taking too long, contact PayPal technical support.

Order Already Captured

Returns from the Orders v2 API. Refer to the Order Already Captured developer document.

Cause
The PayPal order is already in "captured" status, meaning payment is complete and funds have been transferred to your account. No new captures can be created on this order. This happens if you're using intent="SALE" which only allows one capture per order, or if your system didn't record the success of the first capture attempt and tries again.

Impact
If you've only captured part of the order amount, you cannot capture the remaining amount unless you create a new PayPal order. There's no impact to your customer if you only intended to have one capture, but your system may be out of sync with PayPal's records.

Resolution
If you want multiple captures, use intent="AUTHORIZE" instead of intent="SALE". This creates an authorization first, allowing multiple captures afterward. Make sure the final_capture parameter is set to false in your capture authorized payment API call to allow additional captures. Use a unique invoice_id for each capture. Keep track of successful API responses to avoid duplicate calls. Consider using PayPal webhooks to receive automatic updates about payment status changes.

Order Not Approved

Returns from the Payments v1 or Orders v2 APIs. Refer to the Order Not Approved developer document.

Cause
Your customer started but didn't complete the PayPal checkout process, or the request may be missing required payment information.

Impact
The payment is declined and not processed, causing purchase delays.

Resolution
Make sure your customer is redirected to the 'rel':'approve' URL that PayPal provides when you create an order. This takes them to the PayPal checkout flow to approve the payment. Ensure your request includes all required payment information.

Payee Not Enabled For Card Processing

Returns from the Orders v2 API. Refer to the Payee Not Enabled For Card Processing developer document.

Cause
This error appears when your account is not set up to accept credit/debit card payments. The payment won't go through until you enable card payments on your account. This error may also appear if you haven't completed all the steps to accept payments with PayPal Complete Payments.

Impact
Your customers cannot complete their purchases when they try to pay by card. This could lead to lost sales if not fixed quickly. This affects all your customers trying to pay by card, not just one person.

Resolution
Make sure you've completed all the required setup steps. If you're using PayPal Complete Payments, try going through the setup process again and make sure to select the option for card payments. If you still have problems, contact PayPal Technical support. If someone else manages your PayPal account setup, ask them to contact PayPal directly to enable card payments on your account.

Redirect Payer for Alternate Funding

Returns from the Payments v1 or Orders v2 APIs. Refer to the Redirect Payer For Alternate Funding developer document.

Cause
This error appears when your customer's chosen payment method in their PayPal wallet has an issue.

Impact
Your customers cannot complete their purchases when they try to pay by card. This could lead to lost sales if not fixed quickly. This affects all your customers trying to pay by card, not just one person.

Resolution

• Show your customer a message explaining their payment didn't go through and they need to choose a different payment method.
• Direct them back to PayPal checkout so they can select another payment option.
• If problems continue, suggest they try paying with a credit card instead.
• If they still face issues, recommend they contact PayPal directly about their account.
• Use simple, clear instructions to help your customer complete their purchase smoothly.

Referenced Card Expired

Returns from the Orders v2 or Vault v3 APIs. Refer to the Referenced Card Expired developer document.

Cause
This error happens when a buyer tries to pay using a saved credit or debit card, but the card on file has expired. Because of this, the payment can't be processed. The buyer will need to use a different card or choose another payment method to finish their purchase.

Impact
The payment stops, and the buyer can't complete their order. If this isn't fixed quickly, you might lose the sale.

Resolution

• Enable Real-Time Account Updater (RTAU): If you're using PayPal Complete Payments with advanced credit and debit cards, turn on Real-Time Account Updater (RTAU). This feature automatically updates your customers' saved cards with new expiration dates whenever their cards are renewed, helping to avoid expired card errors.
  • RTAU for direct merchants
  • RTAU for multiparty
• Display the error message clearly: Let your customer know their saved card has expired.
• Update the saved payment token: When you get a new payment token from the customer, update it in your system. Make sure you delete the old, expired token from your records and the PayPal vault.
• Giving clear, simple instructions to your customer will help them complete their payment easily, reducing the chance they'll abandon their purchase.

Shipping Address Invalid

Returns from the Payments v1 or Orders v2 APIs. Refer to the Shipping Address Invalid developer document.

Cause
Your customer may have missed important address fields like street address, city, or state. The address format might be incorrect, or your system might not be correctly sending the complete address in the request.

Impact
Your customer can't complete their purchase, which could result in a lost sale if not fixed quickly.

Resolution
Add form validation to ensure all required address fields are completed correctly before submitting. Consider using address validation tools to ensure addresses follow the correct format. Check your systems to make sure all address information is being correctly captured and included in your requests.

Token ID Not Found

Returns from the Payments v1 or Orders v2 APIs.Refer to the Token ID Not Found developer document.

Cause
This error happens when PayPal cannot recognize the token ID provided during checkout. Common reasons are the token might have a typo, or the account making the request may not have proper permission to use the token.

Impact
When this error occurs, the payment process stops, and your customer cannot complete their purchase. If this isn't fixed quickly, it could lead to lost sales.

Resolution
Check permissions to ensure the correct PayPal account has granted the necessary permissions. Also, review your code to confirm the token ID hasn't been changed accidentally. If the token is invalid or expired, create a new one and use it in your request.