## TL;DR

INSTRUMENT_DECLINED on a vaulted payment token retry means the issuer declined the stored instrument: the token is fine, the underlying card or funding source said no. Do not retry the same token in a loop; ask the customer for a new payment method or re-vault the updated instrument, then charge the new token. Treat the vaulted token as stale for this customer.

```text
paypal INSTRUMENT_DECLINED on a vaulted payment token retry
```

## Use this when

- PayPal returns INSTRUMENT_DECLINED on a vaulted payment token retry
- A saved payment method that worked before now declines
- You need fallback logic for stale vaulted instruments

## Not for this skill when

- The vault token itself is invalid or expired (token problem, not decline)
- This is the first charge on a newly vaulted instrument
- You are debugging the vault creation API

## Steps

1. Confirm the decline is INSTRUMENT_DECLINED on the retry, not a token error.
   Expected: You know the instrument was declined.
2. Stop automatic retries against the same token.
   Expected: The loop is broken.
3. Notify the customer that their saved payment method was declined and ask for a new one.
   Expected: The customer supplies a working instrument.
4. Vault the new instrument and charge the new token.
   Expected: The payment succeeds.
5. Mark the old token as unusable for this customer so scheduled retries skip it.
   Expected: No future retry hits the dead instrument.

## Tool compatibility

PayPal vaulted payment tokens and the payments API; INSTRUMENT_DECLINED is an issuer-side decline surfaced by PayPal.

## Variant phrasings

### paypal vaulted token declined retry

Short form of the same failure.

### paypal INSTRUMENT_DECLINED saved card

The saved-instrument angle.

### paypal payment token stale decline

The staleness framing.

## Why it happens

A vaulted token stands in for the underlying instrument, but the issuer re-evaluates every charge: an expired card, a closed account, or a changed risk profile turns a previously good token into a declined one. PayPal surfaces this as INSTRUMENT_DECLINED to distinguish it from token problems. Retrying the same token replays the same issuer decision, so the only fix is a new instrument. The token did not break; what it points to did.

## Edge cases / pitfalls

- Cards expire on a schedule: proactively prompt customers to update instruments before the expiry month.
- Network tokens (where supported) survive card reissuance better than raw PAN vaulting.
- Log the decline distinctly from token errors so your retry logic branches correctly.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tzBspqHRgyX7jsegZUWZLw