How decline categories work

Background

Every declined transaction comes back with a code that tells you who declined it and why. APT groups them into four buckets so retry logic stays sane.

The four buckets

• Soft decline (e.g., 05 Do Not Honor, 51 Insufficient Funds) — temporary; retrying later or via Account Updater often succeeds.
• Hard decline (e.g., 14 Invalid Card, 54 Expired) — do not retry the same card. Prompt for a new payment method.
• Risk decline (e.g., 59 Suspected Fraud) — review velocity and AVS/CVV signals before retrying.
• Gateway decline — the request never reached the issuer (validation, network, or rate-limit). Inspect the API error envelope.

How to use this

Wire your retry policy to the bucket, not the raw code. APT exposes a `decline_category` field on every failed transaction so you do not have to maintain the mapping yourself.