Unprocessable entity
PayPal cannot process your request because it is incorrect or fails business rules. The issues below can cause an UNPROCESSABLE_ENTITY error.
If an issue persists or you have further questions, contact PayPal support.
AGREEMENT_ALREADY_CANCELLED
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - 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. | - Disrupted workflows: Workflows that use the billing agreement ID can be disrupted, which can lead to failures in other business operations. | - 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. |
CANNOT_PAY_SELF
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - Duplicate reference: The transaction or billing agreement attempts to reference the sender and receiver of payment as the same entity, which is invalid. | - 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. | - 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. |
CARD_EXPIRED
Returns from the PayPal Orders v2 or Payments v1 APIs.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - 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. |
CURRENCY_NOT_SUPPORTED
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 API.
| Cause | Impact | Resolution |
|---|---|---|
- 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. | - Rejected requests: The system prevents the completion of billing operations, potentially affecting liquidity and payer satisfaction. | - 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 | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - Improper configuration: The merchant account did not enable or properly configure reference transactions. - Permission issue: The requesting account lacks permissions to manage reference transactions. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - You already authorized this PayPal order. - You can only authorize an order once with intent="AUTHORIZE". - Duplicate requests may happen if you missed the first response. - Network issues or delays may cause missed responses. | PayPal declines the second authorization. You cannot split the authorization into parts. | - Authorize the full order amount in one request, then make multiple captures if needed. - Set final_capture="false" in capture requests for split shipments. - Use PayPal webhooks to track order status. - If your API call times out, contact PayPal support. |
ORDER_ALREADY_CAPTURED
Returns from the Orders v2 API.
| Cause | Impact | Resolution |
|---|---|---|
| - You already captured this order. Payment is complete. - You can only capture an order once with intent="SALE". - Duplicate requests may happen if you missed the first capture response. | If you only captured part of the amount, you cannot capture the rest unless you create a new order. - If you meant to capture once, there is no payer impact. | - Use intent="AUTHORIZE" if you need to capture more than once. - For single captures, make sure you record the API response to avoid duplicates. - Use PayPal webhooks to track payment status. |
ORDER_NOT_APPROVED
Returns from the Payments v1 or Orders v2 APIs.
| Cause | Impact | Resolution |
|---|---|---|
| - The payer did not approve the payment. - The request may not include a valid payment_source. | PayPal declines the payment. The payment does not go through. This can delay the purchase. | - Send the payer to the approval URL (rel:approve) from the Create Order call. - Make sure the request includes a valid payment_source. |
PAYER_ACCOUNT_LOCKED_OR_CLOSED
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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. |
PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING
Returns from the Orders v2 API.
| Cause | Impact | Resolution |
|---|---|---|
| - The payee's account is not set up to take card payments. - The payee has not finished onboarding for PayPal Complete Payments. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. - All payers trying to pay this payee will see this error. | - Make sure the payee finished onboarding and enabled card payments. - If the payee manages onboarding, ask them to contact PayPal to turn on card payments. |
PREVIOUS_REQUEST_IN_PROGRESS
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 Payments v1 or Orders v2 APIs.
| Cause | Impact | Resolution |
|---|---|---|
| - The payment failed because of a problem with the payer's chosen payment method. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Show an error message that the payment did not go through. - Send the payer to PayPal checkout to pick another payment method. - If the problem continues, ask the payer to use a different payment method or contact PayPal. |
REDIRECT_PAYER_FOR_ALTERNATE_FUNDING
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - Insufficient funds: The payer's account may not have enough funds or credit to cover the transaction amount. - Payment method issue: The payment instrument, such as a credit card, is expired or canceled. - Account limitations: The payer's PayPal account might have limitations or restrictions. - Unsupported method: The transaction does not support the selected payment method. | - Incomplete transactions: The payer cannot complete the transaction with the selected payment method. - User experience impact: Reselecting a payment method can add additional steps for the user and delay transaction processing. | - Change payment method: Inform the user to change their payment method, then retry the transaction. - Implement alternative payment mechanism: If supported, develop business logic that redirects users to alternative payment methods, then retry the transaction. |
REFERENCED_CARD_EXPIRED
Returns from the Orders v2 or Vault v3 APIs.
| Cause | Impact | Resolution |
|---|---|---|
| - The transaction uses a saved payment token, but the card is expired. - The payer must use a different card or payment method. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Turn on Real-Time Account Updater (RTAU) to keep card expiration dates up to date. - Show an error message if the saved card is expired. - Update the saved payment token after you get a new one. - Give the payer clear steps to finish the payment. |
SHIPPING_ADDRESS_INVALID
Returns from the Payments v1 or Orders v2 APIs.
| Cause | Impact | Resolution |
|---|---|---|
| - Some address fields are missing or incomplete. - The address format is wrong. - System issues prevent the address from being sent correctly. | PayPal declines the payment. The payment does not go through. This can delay the purchase. | - Check that all required address fields are filled in. - Use address validation tools to fix the format. - Make sure your system sends all address fields in the API request. |
SHIPPING_ADDRESS_INVALID
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - PayPal does not recognize the token ID. - The token may be wrong, mistyped, or the caller does not have permission. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Make sure the receiving account gave the needed permissions. - Check that the token ID is correct. - If the token is wrong or expired, create a new token. |
TRANSACTION_REFUSED
Returns from the Billing Agreements API.
| Cause | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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 | Impact | Resolution |
|---|---|---|
| - 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. | - 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. | - 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. |