PayPal · Decline codes
What does the PayPal PAYER_ACTION_REQUIRED error mean?
Checked
PayPal's PAYER_ACTION_REQUIRED error means the payment can't complete until the buyer takes an action; PayPal's instruction is to "instruct the buyer to return to PayPal." Resubmitting without the buyer will fail again, so send them back to PayPal. On a saved PayPal subscription the buyer is not present, so the store has to bring them back.
- PayPal description
- Transaction cannot complete successfully, instruct the buyer to return to PayPal.
- Type
- Buyer action needed
- Who declined
- PayPal
- Retry
- Only after the buyer completes the step in PayPal
- Shopper action
- Return to PayPal and complete the step shown
- Merchant action
- Send the buyer back to PayPal; don't resubmit blindly
- PlatformDTC renewal
- No blind retry; customer asked to confirm with their bank
What PlatformDTC does
PlatformDTC treats PAYER_ACTION_REQUIRED as a payment that needs the customer. On either retry schedule (the default Fixed schedule or Smart retry), a renewal declined this way is never retried blindly, because nobody is there to respond: the subscription is held past due and the customer gets an email asking them to confirm the payment, plus a signed one-click link to fix it, re-sent up to 4 times per billing cycle.
Why it happens
PayPal needs something from the buyer before it can finish: an approval or a verification step.
What the shopper can do
Open PayPal again from the checkout or the email you received and finish the step it shows.
What the store can do
Redirect the buyer to PayPal's approval link instead of retrying.
For subscriptions, email the customer: only they can complete the step.
For developers
The issue arrives in details[0].issue. In Orders v2 an order or vault setup token can also sit in status PAYER_ACTION_REQUIRED with a payer-action link in its links array; send the buyer there and capture after they return.
Frequently asked questions
- Why can't a renewal complete PAYER_ACTION_REQUIRED on its own?
- Because the action belongs to the buyer. Retrying without them returns the same error.
- Is PAYER_ACTION_REQUIRED a decline?
- Not a refusal of funds; it's a pause until the buyer acts.
Sources
- Orders v2 API errors — PayPal
- Orders v2 API reference — PayPal
Related
- INSTRUMENT_DECLINED — Instrument declined: the card or bank in the buyer's PayPal was refused.
- PAYER_CANNOT_PAY — Payer cannot pay: this buyer's and this seller's PayPal settings don't allow the payment.
- 5650 — SCA required: the bank needs the cardholder to authenticate the payment.
- TRANSACTION_REFUSED — Transaction refused: PayPal refused the request without a specific reason.
- PAYEE_ACCOUNT_RESTRICTED — Payee account restricted: the merchant's PayPal account is restricted.
- PAYER_ACCOUNT_LOCKED_OR_CLOSED — Payer account locked or closed: the buyer's PayPal account can't be used.
- COMPLIANCE_VIOLATION — Compliance violation: PayPal declined the payment on compliance grounds.
- MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED — Max payment attempts exceeded: too many attempts on this order.