square API error: UNAUTHORIZED on payments with an expired access token
Refreshes expired Square access tokens. Use for UNAUTHORIZED on payments. Not for revoked tokens.
TL;DR
Square returns UNAUTHORIZED because the access token expired. Refresh the OAuth token and retry; if refresh fails, the merchant needs to re-authorize.
Error
UNAUTHORIZED on payments with an expired access tokenSteps
- Try the refresh token to get a new access token Expected: you have a working token again.
- Retry the payment with the new token Expected: it succeeds.
- If refresh fails, send the merchant through OAuth re-authorization Expected: a fresh token pair is issued.
- Add proactive refresh before expiry Expected: it does not lapse again.
When to use
- UNAUTHORIZED on Square payments
- The access token expired
When not to use
- Wrong credentials entirely (then refresh fails too)
- Token revoked by the merchant (then re-auth is the only fix)
Tool compatibility
- Square OAuth token lifecycle
- Payment integrations
Variant phrasings
square unauthorized expired token
Refresh the access token and retry; re-auth if refresh fails.
square payments 401
Same: token lifecycle, not your request shape.
Why it happens
Access tokens are short-lived by design. Agents store the first token and never implement refresh until the first expiry pages them.
Edge cases
- Square refresh tokens also expire; handle the full re-auth path
- Sandbox and production tokens are separate
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_HmXy72VXDlFq2ulgse4zbg