> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.paypal.com/us/cshelp/technical).

<Heading level={2} id="agreement_already_cancelled">
  AGREEMENT\_ALREADY\_CANCELLED
</Heading>

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. <br /> - Oversight: The payer misunderstood the current agreement status. <br /> - 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. <br /> - Service disruption: Unintended or improperly communicated canceled billing agreements can disrupt service or billing processes. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration and confusion among payers. | - Verify agreement status: Confirm the canceled status of the billing agreement. <br /> - Review business logic: Ensure that the integrated system properly checks the status before attempting operations. <br /> - Communicate with payers: Inform the payer about the unintended canceled billing agreement to resolve issues. <br /> - Create a new billing agreement. |

<Heading level={2} id="billing_agreement_not_found">
  BILLING\_AGREEMENT\_NOT\_FOUND
</Heading>

Returns from the Billing Agreements API.

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

<Heading level={2} id="cannot_pay_self">
  CANNOT\_PAY\_SELF
</Heading>

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. <br /> - 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. <br /> - Review API request: Ensure you use distinct PayPal account IDs or email addresses for the sender and receiver. <br /> - Implement validation checks: Ensure that your application checks to prevent users from setting up billing agreements with duplicate entities. <br /> - Verify account details: Ensure that your application uses the correct account details for transactions and billing agreements. <br /> - Implement retry mechanism: Develop business logic that waits a short period before attempting the request again, gradually increasing the wait time with each attempt. |

<Heading level={2} id="card_expired">
  CARD\_EXPIRED
</Heading>

Returns from the PayPal Orders v2 or Payments v1 APIs.

| Cause                                                                                                                                                          | Impact                                                                                     | Resolution                                                                                                                                                                                 |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You tried to pay with an expired card. <br /> - An expired card cannot be used for payments. <br /> - 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. <br /> - Ask the payer to use a different card or payment method. <br /> - Help the payer switch payment methods and finish the payment. |

<Heading level={2} id="currency_not_supported">
  CURRENCY\_NOT\_SUPPORTED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                           | Impact                                                                                                                                                                                                                        | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Unsupported code: PayPal does not support the currency code in the API request. <br /> - Region limitations: The region from which the API was initiated may not support the currency code. <br /> - 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. <br /> - 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. <br /> - Verify currency settings: Confirm that your PayPal business account can use the necessary [currencies](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/). <br /> - Cross-check regional restrictions: Ensure that your region does not restrict the currency used in your transaction or billing agreement. <br /> - Change currency codes: Change the currency code used in your API request to a supported currency for your location or account. |

<Heading level={2} id="duplicate_invoice_id">
  DUPLICATE\_INVOICE\_ID
</Heading>

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`. <br /> - 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](https://www.paypal.com/us/cshelp/contact-us): If your workflow requires duplicate invoice IDs, contact customer support. <br /> - Confirm invoice usage: Confirm the use of unique invoice IDs in your billing agreements and transactions. <br /> - Implement invoice ID mechanisms: Develop logic that generates a unique invoice ID for each transaction and billing agreement. <br /> - Incorporate logs: Track and verify invoice IDs in the application to prevent reuse and assist with future debugging. |

<Heading level={2} id="instrument_declined">
  INSTRUMENT\_DECLINED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Impact                                                                                                                                                                                                                                                                                                                            | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Billing address issues: PayPal could not confirm the billing address for the payment method. <br /> - Expired card: The payer used an expired or canceled payment instrument, such as a credit card. <br /> - Declined transaction: The bank or card issuer declined the transaction due to reasons such as suspected fraud or account restrictions. <br /> - Potential risk: The payer account may have insufficient funds, may pose a risk, or may have encountered a compliance issue. <br /> - 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. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. <br /> - 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. <br /> - Fund availability: Confirm with the payer that their account holds sufficient funds or is within their credit limit. <br /> - Contact financial institution: Encourage payers to contact their bank or card issuer to resolve any temporary holds or restrictions. <br /> - Update billing instrument: If the payer used an expired or invalid instrument, ask the payer to update their payment information. |

<Heading level={2} id="merchant_not_enabled_for_reference_transaction">
  MERCHANT\_NOT\_ENABLED\_FOR\_REFERENCE\_TRANSACTION
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                    | Impact                                                                                                                                                                                                                                    | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Improper configuration: The merchant account did not enable or properly configure reference transactions. <br /> - Permission issue: The requesting account lacks permissions to manage reference transactions. <br /> | - Disrupted workflows: The merchant cannot process future payments from the payer without manually acquiring authorization again. <br /> - 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](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/). <br /> - 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](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/). |

<Heading level={2} id="not_enabled_for_channel_initiated_billing">
  NOT\_ENABLED\_FOR\_CHANNEL\_INITIATED\_BILLING
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                           | Impact                                                                                                                                                                                                                                   | Resolution                                                                                                                                                                                                                                            |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - No approval: The merchant did not request or was not approved for channel-initiated billing. <br /> - Improper configuration: The merchant account settings do not include necessary features, configurations, or permissions. <br /> - 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. <br /> - 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. <br /> - Review account settings: Ensure that your account settings support the desired billing features. |

<Heading level={2} id="order_already_authorized">
  ORDER\_ALREADY\_AUTHORIZED
</Heading>

Returns from the Payments v2 or Orders v2 APIs.

| Cause                                                                                                                                                                                                                                                       | Impact                                                                                   | Resolution                                                                                                                                                                                                                                                                              |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You already authorized this PayPal order. <br /> - You can only authorize an order once with `intent="AUTHORIZE"`. <br /> - Duplicate requests may happen if you missed the first response. <br /> - 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. <br /> - Set `final_capture="false"` in capture requests for split shipments. <br /> - Use PayPal webhooks to track order status. <br /> - If your API call times out, contact PayPal support. |

<Heading level={2} id="order_already_captured">
  ORDER\_ALREADY\_CAPTURED
</Heading>

Returns from the Orders v2 API.

| Cause                                                                                                                                                                                                      | Impact                                                                                                                                                               | Resolution                                                                                                                                                                                                     |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You already captured this order. Payment is complete. <br /> - You can only capture an order once with `intent="SALE"`. <br /> - 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. <br /> - If you meant to capture once, there is no payer impact. | - Use `intent="AUTHORIZE"` if you need to capture more than once. <br /> - For single captures, make sure you record the API response to avoid duplicates.<br />- Use PayPal webhooks to track payment status. |

<Heading level={2} id="order_not_approved">
  ORDER\_NOT\_APPROVED
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                   | Impact                                                                                     | Resolution                                                                                                                                         |
| :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The payer did not approve the payment. <br /> - 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. <br /> - Make sure the request includes a valid `payment_source`. |

<Heading level={2} id="payer_account_locked_or_closed">
  PAYER\_ACCOUNT\_LOCKED\_OR\_CLOSED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                 | Impact                                                                                                                                                                                                                                                 | Resolution                                                                                                                                                                                                                                                |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Account lock: Violation of [PayPal’s Acceptable Use Policy](https://www.paypal.com/us/legalhub/paypal/acceptableuse-full) due to suspicious activities can lead to an account lock or security concerns. <br /> - 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. <br /> - Service operations: Merchants and payers can experience service loss, which can cause revenue loss. | - [Contact customer support](https://www.paypal.com/us/cshelp/contact-us): Work with customer support to resolve the issue. <br /> - Settle account: Resolve debts or disputes that led to the account lock or closure, then retry the billing agreement. |

<Heading level={2} id="payer_cannot_pay">
  PAYER\_CANNOT\_PAY
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Impact                                                                                                                                                                                                                                                                                                                           | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Insufficient funds: The payer does not have enough available funds or credit. <br /> - Account limitations: The payer's account may have limitations or restrictions. <br /> - Unverified account: The payer uses an unverified account or did not perform required updates, which prevents payments. <br /> - Payment method issue: The payer used an expired or canceled payment instrument, such as a credit card. <br /> - 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. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. <br /> - 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. <br /> - Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. <br /> - Configure alternative payment options: Suggest that the payer use a different payment method. <br /> Update account info: Ensure that the payer includes up-to-date account information, such as billing address and linked payment methods. |

<Heading level={2} id="payee_not_enabled_for_card_processing">
  PAYEE\_NOT\_ENABLED\_FOR\_CARD\_PROCESSING
</Heading>

Returns from the Orders v2 API.

| Cause                                                                                                                                   | Impact                                                                                                                                                       | Resolution                                                                                                                                                          |
| :-------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| - The payee's account is not set up to take card payments. <br /> - 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. <br /> - All payers trying to pay this payee will see this error. | - Make sure the payee finished onboarding and enabled card payments. <br /> - If the payee manages onboarding, ask them to contact PayPal to turn on card payments. |

<Heading level={2} id="previous_request_in_progress">
  PREVIOUS\_REQUEST\_IN\_PROGRESS
</Heading>

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. <br /> - 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. <br /> - Queue requests: Process requests sequentially in a queue, allowing each request to complete before initiating the next request. <br /> - 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. |

<Heading level={2} id="redirect_payer_for_alternate_funding">
  REDIRECT\_PAYER\_FOR\_ALTERNATE\_FUNDING
</Heading>

Returns from the Payments v1, and 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. <br /> - Send the payer to PayPal checkout to pick another payment method. <br /> - If the problem continues, ask the payer to use a different payment method or contact PayPal. |

<Heading level={2} id="redirect_payer_for_alternate_funding_billing_agreements">
  REDIRECT\_PAYER\_FOR\_ALTERNATE\_FUNDING
</Heading>

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. <br /> - Payment method issue: The payment instrument, such as a credit card, is expired or canceled. <br /> - Account limitations: The payer's PayPal account might have limitations or restrictions. <br /> - Unsupported method: The transaction does not support the selected payment method. | - Incomplete transactions: The payer cannot complete the transaction with the selected payment method. <br /> - 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. <br /> - Implement alternative payment mechanism: If supported, develop business logic that redirects users to alternative payment methods, then retry the transaction. |

<Heading level={2} id="referenced_card_expired">
  REFERENCED\_CARD\_EXPIRED
</Heading>

Returns from the Orders v2 or Vault v3 APIs.

| Cause                                                                                                                                  | Impact                                                                                     | Resolution                                                                                                                                                                                                                                                                    |
| :------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The transaction uses a saved payment token, but the card is expired. <br /> - 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. <br /> - Show an error message if the saved card is expired. <br /> - Update the saved payment token after you get a new one. <br /> - Give the payer clear steps to finish the payment. |

<Heading level={2} id="shipping_address_invalid">
  SHIPPING\_ADDRESS\_INVALID
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                                                                        | Impact                                                                                     | Resolution                                                                                                                                                                                   |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Some address fields are missing or incomplete. <br /> - The address format is wrong. <br /> - 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. <br /> - Use address validation tools to fix the format. <br /> - Make sure your system sends all address fields in the API request. |

<Heading level={2} id="shipping_address_invalid_billing_agreements">
  SHIPPING\_ADDRESS\_INVALID
</Heading>

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. <br /> - Missing fields: The API request does not contain required shipping address fields. <br /> - Validation failure: The address does not match the standards or validation rules set by PayPal or the postal service of the specified country. <br /> - 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. <br /> - 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. <br /> - Match address: Ensure that the address fields, such as street, city, state, postal code, and country, match the expected format for the specified country. <br /> - Verify country code: Ensure that the country code matches the country name, using address validation tools or services to confirm its accuracy. <br /> - Revise address: Contact the payer to correct or confirm the address details. |

<Heading level={2} id="token_id_not_found">
  TOKEN\_ID\_NOT\_FOUND
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                                        | Impact                                                                                     | Resolution                                                                                                                                                                 |
| :--------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - PayPal does not recognize the token ID. <br /> - 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. <br /> - Check that the token ID is correct. <br /> - If the token is wrong or expired, create a new token. |

<Heading level={2} id="transaction_refused">
  TRANSACTION\_REFUSED
</Heading>

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.​ <br /> - Insufficient funds: The payer's account may not have enough funds or credit to cover the transaction amount. <br /> - Account limitations: The payer's PayPal account might have limitations or restrictions. <br /> - 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. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to payer frustration. <br /> - 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. <br /> - Check account status: Verify that both the payer's and merchant's PayPal accounts operate in good standing without any limitations or restrictions. <br /> - Correct API request: Double-check the API request parameters to ensure they are correct and complete. |

<Heading level={2} id="unsupported_payee_currency">
  UNSUPPORTED\_PAYEE\_CURRENCY
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                 | Impact                                                                                                                                                                                                                                                                            | Resolution                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Account restrictions: The payee account restrictions permit only transactions in certain currencies. <br /> - Disabled currency: The payee did not enable the specified currency in their account settings. <br /> - 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. <br /> - 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. <br /> - Configure account: Ensure that you have enabled the specified currency in your account settings to accept payment from the payee account. <br /> - Currency conversion: Consider using a supported currency or handle currency conversion with PayPal currency conversion services. |