Unprocessable entity

• 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.

• 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.

• 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.

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.

• 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: 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.

• 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.

• 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

  .

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

The payment is declined, and the payment is not processed. This can lead to delays in completing the purchase.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

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.

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.

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.

• 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.

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.

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.

• 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.

• 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.

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.

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.

• 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.

• 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.

• 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.