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.

AGREEMENT_ALREADY_CANCELLED

Returns from the Billing Agreements API.

Cause	Previously canceled: The payer performed an API call to modify, execute, or otherwise interact with a previously canceled billing agreement. Oversight: The payer misunderstood the current agreement status. Business logic error: The system that is integrated with the API improperly checked the agreement status before attempting operations.
Impact	Operations failure: The payer potentially cannot perform operations, such as processing payments, on the canceled agreement. Service disruption: Unintended or improperly communicated canceled billing agreements can disrupt service or billing processes. Payer dissatisfaction: Repeated transaction failures can lead to frustration and confusion among payers.
Resolution	Verify agreement status: Confirm the canceled status of the billing agreement. Review business logic: Ensure that the integrated system properly checks the status before attempting operations. Communicate with payers: Inform the payer about the unintended canceled billing agreement to resolve issues. Create a new billing agreement.

BILLING_AGREEMENT_NOT_FOUND

Returns from the Billing Agreements API.

Cause	Incorrect billing agreement ID: The ID in the API request is incorrect. Improper billing agreement: The API request uses a missing billing agreement. Permission issue: The requesting account lacks permissions to manage the billing agreement.
Impact	Disrupted workflows: Workflows that use the billing agreement ID can be disrupted, which can lead to failures in other business operations.
Resolution	Verify billing agreement ID: Ensure the accuracy of the billing agreement ID in the API request. Check agreement status: Confirm that the billing agreement ID belongs to an active billing agreement. Elevate permission: Ensure that the requesting account holds appropriate permissions to manage the billing agreement.

CARD_EXPIRED

Returns from the PayPal Orders v2 or Payments v1 APIs.

Cause	You tried to pay with an expired card. An expired card cannot be used for payments. The payer must use a different card or payment method.
Impact	PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales.
Resolution	Show an error message that the card is expired. Ask the payer to use a different card or payment method. Help the payer switch payment methods and finish the payment.

CANNOT_PAY_SELF

Returns from the Billing Agreements API.

Cause	Duplicate reference: The transaction or billing agreement attempts to reference the sender and receiver of payment as the same entity, which is invalid.
Impact	Disrupted workflows: Intended payments or subscription setup fail, leading to unprocessable billing agreements and transactions. Disrupted revenue: Failed processes can lead to disruption of automated systems that use billing agreements and ongoing subscriptions.
Resolution	Confirm separation: Ensure that the sender and receiver are different entities. Review API request: Ensure you use distinct PayPal account IDs or email addresses for the sender and receiver. Implement validation checks: Ensure that your application checks to prevent users from setting up billing agreements with duplicate entities. Verify account details: Ensure that your application uses the correct account details for transactions and billing agreements. Implement retry mechanism: Develop business logic that waits a short period before attempting the request again, gradually increasing the wait time with each attempt.

CURRENCY_NOT_SUPPORTED

Returns from the Billing Agreements API.

Cause	Unsupported code: PayPal does not support the currency code in the API request. Region limitations: The region from which the API was initiated may not support the currency code. Account restrictions: The merchant account may have restrictions or limitations on supported currencies.
Impact	Process failure: The billing agreement fails due to the use of unsupported currencies. Revenue loss: Subscriptions or recurring payments do not proceed due to this error, causing delays or issues for the payer.
Resolution	Verify currency support: Confirm that PayPal supports the currency code. Verify currency settings: Confirm that your PayPal business account can use the necessary currencies. Cross-check regional restrictions: Ensure that your region does not restrict the currency used in your transaction or billing agreement. Change currency codes: Change the currency code used in your API request to a supported currency for your location or account.

DUPLICATE_INVOICE_ID

Returns from the Billing Agreements, Payments v1, and Orders v2 APIs.

Cause	- Duplicate invoice ID: The API request uses a duplicate invoice ID. All transactions and billing agreements require a unique `invoice_id`. - Reused invoice ID: The transaction or billing agreement uses a processed invoice ID typically due to a logic error or failure to manually update the ID.
Impact	- Rejected requests: The system prevents the completion of billing operations, potentially affecting liquidity and payer satisfaction.
Resolution	Contact customer support: If your workflow requires duplicate invoice IDs, contact customer support. Confirm invoice usage: Confirm the use of unique invoice IDs in your billing agreements and transactions. Implement invoice ID mechanisms: Develop logic that generates a unique invoice ID for each transaction and billing agreement. Incorporate logs: Track and verify invoice IDs in the application to prevent reuse and assist with future debugging.

INSTRUMENT_DECLINED

Returns from the Billing Agreements API.

Cause	Billing address issues: PayPal could not confirm the billing address for the payment method. Expired card: The payer used an expired or canceled payment instrument, such as a credit card. Declined transaction: The bank or card issuer declined the transaction due to reasons such as suspected fraud or account restrictions. Potential risk: The payer account may have insufficient funds, may pose a risk, or may have encountered a compliance issue. Incorrect billing information: The user entered incorrect information, such as CVV, expiration date, or account number.
Impact	Payment failure: The payer cannot complete the payment, potentially affecting their access to services or products. Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions.
Resolution	Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. Fund availability: Confirm with the payer that their account holds sufficient funds or is within their credit limit. Contact financial institution: Encourage payers to contact their bank or card issuer to resolve any temporary holds or restrictions. Update billing instrument: If the payer used an expired or invalid instrument, ask the payer to update their payment information.

MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION

Returns from the Billing Agreements API.

Cause	Improper configuration: The merchant account did not enable or properly configure reference transactions. Permission issue: The requesting account lacks permissions to manage reference transactions.
Impact	Disrupted workflows: The merchant cannot process future payments from the payer without manually acquiring authorization again. Disrupted revenue: Additional authorization requests can impact post-purchase revenue streams.
Resolution	Contact customer support: Send a request to customer support to enable reference transactions for your account. Enabling reference transactions may require you to provide additional information about your account. For more information, see Initiate future transactions. Verify configurations: Ensure that you configured your account settings to support reference transactions. PayPal may request additional information regarding your account to enable this feature. For more information, see Initiate future transactions.

NOT_ENABLED_FOR_CHANNEL_INITIATED_BILLING

Returns from the Billing Agreements API.

Cause	No approval: The merchant did not request or was not approved for channel-initiated billing. Improper configuration: The merchant account settings do not include necessary features, configurations, or permissions. Account restrictions or limitations: The merchant account may have restrictions or limitations based on their account type or region.
Impact	Process failure: The merchant cannot create or manage their billing agreement. Revenue loss: Subscriptions, recurring payments, or other functionality reliant on channel-initiated billing do not proceed due to this error.
Resolution	Contact customer support: Work with customer support or your account manager to inquire about enabling channel-initiated billing support. Review account settings: Ensure that your account settings support the desired billing features.

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.

PAYER_ACCOUNT_LOCKED_OR_CLOSED

Returns from the Billing Agreements API.

Cause	Account lock: Violation of PayPal’s Acceptable Use Policy due to suspicious activities can lead to an account lock or security concerns. Account closure: The payer or PayPal closed the account due to policy violations or other administrative reasons.
Impact	Billing agreement failure: This error prevents payers from creating or processing billing agreements and their associated transactions. Service operations: Merchants and payers can experience service loss, which can cause revenue loss.
Resolution	Contact customer support: Work with customer support to resolve the issue. Settle account: Resolve debts or disputes that led to the account lock or closure, then retry the billing agreement.

PAYER_CANNOT_PAY

Returns from the Billing Agreements API.

Cause	Insufficient funds: The payer does not have enough available funds or credit. Account limitations: The payer's account may have limitations or restrictions. Unverified account: The payer uses an unverified account or did not perform required updates, which prevents payments. Payment method issue: The payer used an expired or canceled payment instrument, such as a credit card. Account restrictions: The payer account encounters a compliance issue or external issue that restricts payment processing.
Impact	Payment failure: The payer cannot complete the payment, potentially affecting their access to services or products. Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions.
Resolution	Check account status: Verify that both the payer's and merchant's PayPal accounts are in good standing without any limitations or restrictions. Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. Configure alternative payment options: Suggest that the payer use a different payment method. Update account info: Ensure that the payer includes up-to-date account information, such as billing address and linked payment methods.

PREVIOUS_REQUEST_IN_PROGRESS

Returns from the Billing Agreements API.

Cause	Request conflict: Multiple requests conflict for the same resource, such as a billing agreement. PayPal requires the initial request to complete before processing another request.
Impact	Operation hold: Multiple requests cause a halt on new operations on the affected resource until the resource processes the original request. Processing delay: Multiple requests can delay planned modifications or renewals of a resource.
Resolution	Verify request status: Check the status of the previous request to ensure its completion before initiating a new request. Queue requests: Process requests sequentially in a queue, allowing each request to complete before initiating the next request. Implement error handling: Develop business logic to handle this error and respond appropriately, such as notifying users of the delay or logging the error for further analysis.

REDIRECT_PAYER_FOR_ALTERNATE_FUNDING

Returns from the Billing Agreements, Payments v1, and 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, Orders v2 APIs, and Billing Agreements API.

Cause	Incorrect formatting: The API request's shipping address fields (such as street, city, state, postal code, and country) contain formatting errors or invalid characters. Missing fields: The API request does not contain required shipping address fields. Validation failure: The address does not match the standards or validation rules set by PayPal or the postal service of the specified country. Mismatch: The country code and the country name provided may mismatch, causing the error.
Impact	Process failure: The billing agreement, transaction, or subscription setup will not proceed. Workflow disruption: Delays in processing payments or setting up recurring billing agreements can impact payer satisfaction and business operations.
Resolution	Verify fields: Verify that all required fields in the shipping address use correct formatting. Match address: Ensure that the address fields, such as street, city, state, postal code, and country, match the expected format for the specified country. Verify country code: Ensure that the country code matches the country name, using address validation tools or services to confirm its accuracy. Revise address: Contact the payer to correct or confirm the address details.

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.

TRANSACTION_REFUSED

Returns from the Billing Agreements API.

Cause	Payment method issues: The payment method linked to the billing agreement might be invalid, expired, or otherwise unable to process the payment. Insufficient funds: The payer's account may not have enough funds or credit to cover the transaction amount. Account limitations: The payer's PayPal account might have limitations or restrictions. Risk factors: If PayPal detects any potential risks based on merchant history or if there's high risk associated with the transaction, PayPal will refuse the transaction.
Impact	Payment failure: The payer's failure to complete the payment can potentially affect their access to services or products. Payer dissatisfaction: Repeated transaction failures can lead to payer frustration. Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions.
Resolution	Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. Check account status: Verify that both the payer's and merchant's PayPal accounts operate in good standing without any limitations or restrictions. Correct API request: Double-check the API request parameters to ensure they are correct and complete.

UNSUPPORTED_PAYEE_CURRENCY

Returns from the Billing Agreements API.

Cause	Account restrictions: The payee account restrictions permit only transactions in certain currencies. Disabled currency: The payee did not enable the specified currency in their account settings. Region limitations: Certain regions do not make available specific currencies for the merchant account, resulting in a currency mismatch during a transaction.
Impact	Process failure: The merchant cannot create or manage their billing agreement. Impacted business operations: PayPal does not record failed transactions, which prevents tracking of fund transfer issues and could impact subscription services or billing agreements.
Resolution	Confirm that PayPal supports the currency code. Configure account: Ensure that you have enabled the specified currency in your account settings to accept payment from the payee account. Currency conversion: Consider using a supported currency or handle currency conversion with PayPal currency conversion services.