Should I retry INSTRUMENT_DECLINED?

At checkout, restart so the buyer can choose another funding source, as PayPal recommends. For subscriptions, spaced retries give the buyer's card or balance time to recover, since PayPal names no reason that rules recovery out.

Is INSTRUMENT_DECLINED the buyer's PayPal account being blocked?

No. It's about the specific card or bank they picked. PayPal uses other errors, such as PAYER_ACCOUNT_LOCKED_OR_CLOSED, for account problems.

PayPal · Decline codes

What does the PayPal INSTRUMENT_DECLINED error mean?

Checked October 31, 2026

PayPal's INSTRUMENT_DECLINED error means the funding source the buyer chose, a card or bank account in their PayPal wallet, was declined by the processor or bank, or can't be used for this payment. PayPal lists causes such as a wrong billing address, a card over its limit, or a bank denial. The fix is to restart the payment so the buyer can pick another funding source.

PayPal description: The instrument presented was either declined by the processor or bank, or it can't be used for this payment.
Type: Soft decline
Who declined: The processor or bank behind the PayPal funding source
Retry: Yes, a few days later; switch method if it repeats
Shopper action: Choose another card or bank in PayPal and pay again
Merchant action: Restart the payment so the buyer can pick another source
PlatformDTC renewal (Smart retry): PayPal ladder: up to 7 attempts, 3+ days apart, aimed at payday

What PlatformDTC does

PlatformDTC treats INSTRUMENT_DECLINED as a generic PayPal refusal. With Smart retry on, a PayPal subscription renewal declined this way rides the longer PayPal ladder: up to 7 attempts, each at least 3 days after the last, moved to the subscriber's next payday when one falls within a week, inside a window of at least 24 days. When retries run out the subscription is held past due, not cancelled. On PayPal card payments, any processor code PlatformDTC doesn't map is also recorded as INSTRUMENT_DECLINED, with the raw code kept.

Why it happens

PayPal returns this when the payer's funding source fails: the card or bank inside their PayPal wallet said no. PayPal's funding-failure guide lists an incorrect billing address, a transaction over the card limit, and a card issuer denial as examples.

What the shopper can do

Go back into PayPal and pick a different card, bank account or your PayPal balance.

Or check the card's billing address and limit, then try again.

What the store can do

Restart the payment flow so the buyer sees PayPal's funding choices again; don't just show an error.

On renewals, space retries over days; the buyer's balance may recover by payday.

For developers

When you capture from your server and the Orders API returns INSTRUMENT_DECLINED (in details[0].issue of the error body), restart the payment: in the JavaScript SDK, call actions.restart() inside onApprove. PayPal says restarting is required if you call the Orders API directly from your server.

If you capture with actions.order.capture() in the browser, PayPal's script restarts the checkout flow automatically and prompts the payer to pick another funding source.

Frequently asked questions

Should I retry INSTRUMENT_DECLINED?: At checkout, restart so the buyer can choose another funding source, as PayPal recommends. For subscriptions, spaced retries give the buyer's card or balance time to recover, since PayPal names no reason that rules recovery out.
Is INSTRUMENT_DECLINED the buyer's PayPal account being blocked?: No. It's about the specific card or bank they picked. PayPal uses other errors, such as PAYER_ACCOUNT_LOCKED_OR_CLOSED, for account problems.