Troubleshooting
The following table lists common Orders v2 API issues and how to resolve them.
Issue | Action |
---|---|
AMOUNT_MISMATCH |
Ensure the total amount equals the sum of line items, taxes, and discounts. This error can occur when sale amounts aren't reflected in the API request. |
CANNOT_BE_NEGATIVE |
Ensure the amount is positive, with no more than two decimal places. |
CANNOT_BE_ZERO_OR_NEGATIVE |
Ensure the amount is a positive, non-zero number with no more than two decimal places. |
CARD_EXPIRED |
Surface the error to the buyer and ask them to use a different card. |
CURRENCY_NOT_SUPPORTED |
Retry with a PayPal-supported currency. Ensure the receiving PayPal account is configured to accept the currency. For a list of currencies that PayPal supports, see Currency codes. |
DECIMAL_PRECISION |
Round up the amount to two decimal places and retry. If issues persist, contact PayPal support and share the debug_id returned in the API response. |
DECIMALS_NOT_SUPPORTED |
Adjust the amount to match the number of decimal places the currency supports. |
DUPLICATE_INVOICE_ID |
Send a different invoice_id . If you must use the same invoice_id and the error persists, contact PayPal support. |
INCOMPATIBLE_PARAMETER_VALUE |
Ensure the parameters specified in the API request match the expected data types. Refer to field-level specifications. |
INVALID_PARAMETER_SYNTAX |
Ensure the API request JSON is syntactically correct and conforms to the PayPal API request format. If the problem persists, contact PayPal support and share the debug_id returned in the API response. |
INVALID_RESOURCE_ID |
Check the resource ID and try again. If the resource ID belongs to a different PayPal account, check the scopes and permissions for the receiving account. |
INVALID_STRING_LENGTH |
Ensure text fields aren't too long or missing required data. For expected string lengths, see the Orders API documentation. |
ITEM_TOTAL_MISMATCH |
Ensure the item totals match the quantity total. |
MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED |
Ask the buyer to use a different payment method. |
MISSING_REQUIRED_PARAMETER |
Ensure the JSON conforms to the PayPal API request format and includes all required fields. Review the API request for required parameters. If the problem persists, contact PayPal support and share the debug_id returned in the API response. |
ORDER_ALREADY_AUTHORIZED |
If the merchant wants to proceed with the order, call capture as the funds have been authorized. If the authorization is over 3 days old, the merchant can reauthorize the funds before capturing. |
ORDER_ALREADY_CAPTURED |
No further action is needed. Make a GET call on the order ID to get the capture ID, or the PayPal transaction ID. If this is a multi-capture, split shipment use case, move to intent=AUTHORIZE as authorizations support multiple captures. |
ORDER_NOT_APPROVED |
The buyer must go through PayPal checkout again to approve the order. Redirect the buyer to the 'rel':'approve' URL returned as part of the HATEOAS links within the create order call, or provide a valid payment_source in the request. |
PAYEE_ACCOUNT_RESTRICTED |
Contact PayPal customer support to lift restrictions on the receiving account. If you're a marketplace sending funds to a seller, reach out to the seller to resolve restrictions with PayPal. |
PAYEE_NOT_CONSENTED |
Ensure the caller API account has consent to collect partner fees for the payee. Make sure to add PARTNER_FEE to the list of capabilities when taking the payee through the signup flow. If PARTNER_FEE is already added or if errors persist, contact PayPal support. |
PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING |
Contact PayPal support to check the merchant or payee accouunt configuration. |
PAYER_ACTION_REQUIRED |
Redirect the buyer to the 'rel':'payer-action' HATEOAS link returned as part of the response before authorizing or capturing the order. Some payment methods require a webhook subscription to inform you of asynchronous buyer actions before the capture succeeds. |
PERMISSION_DENIED |
Check if the resource ID belongs to the PayPal account making the API call. If the ID belongs to a different account, ensure you've granted permissions and scopes to access the other account's resources. |
POSTAL_CODE_REQUIRED |
Add a postal code to the request and retry. |
REDIRECT_PAYER_FOR_ALTERNATE_FUNDING |
Redirect the buyer to choose a different payment method. Within PayPal, the buyer can add a different payment method to their wallet, or use a different card. |
REFERENCED_CARD_EXPIRED |
Contact the buyer to request updated card information, otherwise future attempts will fail. |
SHIPPING_ADDRESS_INVALID |
Fix the shipping address and retry. If using saved payment details, contact the buyer to provide the correct shipping address. |
TOKEN_ID_NOT_FOUND |
Validate if the payment token passed is correct. If the merchant PayPal account is making API calls on behalf of a different PayPal account, ensure the recipient account grants permissions to the account making the API call. |
UNPROCESSABLE_ENTITY |
Reach out to PayPal support with the debug_id or correlation_id from the response header, or for legacy integrations, in the body or response parameters. |
VALIDATION_ERROR |
Inform the buyer that the card number entered is incorrect and request them to input the correct number. |