Download the PHP package ianfoxdev/decline-codes without Composer

decline-codes

Payment decline codes normalized across card networks and payment providers, and a retry policy that follows the networks' reattempt rules. Every rule names its source and the edition of the document it comes from. The data is JSON, so other languages can use it too.

Status: v0.1. Until 1.0 a minor version may change the API; such changes are marked BREAKING in the CHANGELOG. A network's rule change is a minor release too, and the CHANGELOG names the rule and the edition.

Retrying declined payments usually runs on one schedule for every decline: tomorrow, in three days, in a week. Two things go wrong with that.

• Some declines must never be retried. Visa's category 1 (lost, stolen, closed account, "pick up") and Mastercard's Merchant Advice Codes 03 and 21 mean the issuer will not approve this card again. Each retry after them can be charged as an excessive retry.
• The rest have a limit. Visa allows up to 20 reattempts in 30 days (Visa Core Rules, 18 April 2026, Table 7-2). Until recently the rule said 15, and most pages and libraries still do. Mastercard asks to stop after 10 consecutive declines at one merchant in 24 hours, and sends codes that say how long to wait.

Install

PHP 8.3 or later, no dependencies.

Example

After a Mastercard decline with Merchant Advice Code 03 the same call returns:

examples/renewals runs five declined renewals: a schedule, a Mastercard delay, a Stripe "generic_decline" that is really a stolen card, a wrong CVC, and an hourly retrier stopped by Visa's limit.

What you get for a decline

$reason->forCustomer($catalog) turns lost, stolen and fraud reasons into generic_decline, as Stripe advises: the message should not help someone testing stolen cards.

The retry policy

decide() takes the attempts with one card at your merchant, oldest first, and returns a Decision: retry_at a time, never, needs_customer (new card data, authentication, a PIN) or give_up (your schedule is out of attempts). The rule that decided is in rule, its source in source.

The network rules are a ceiling. Your schedule runs below them and cannot lift them:

The default schedule makes at most 8 attempts, as Stripe recommends. After a "later" decline it waits 1, 2, 3, 5, 7, 10 and 14 days; after a technical one, 10 minutes, 1 hour, 6 hours, then a day. Pass your own Schedule to change it.

A test runs an eager retrier (no limit of its own, retrying the moment the policy allows) for 400 cards over 90 days against random issuer answers, and checks every network rule over every card's whole history.

Where the data comes from

Where secondary sources disagree, the stricter value is used and the record says so. One example: Braintree describes the Mastercard 35-in-30-days rule in a Canada update; other processors describe it without a region, so it applies everywhere here. Codes 76 to 89 are reserved for private use in ISO 8583 and mean different things per network (82 is a CVV failure at Visa and a policy decline at Mastercard), so the ISO profile does not guess them.

When a network changes a rule, the data changes in a minor release and the CHANGELOG says which rule, which edition, and what it was before.

More: docs/usage.md.

Not yet

Network fees for excessive retries (not in the public rules), storing attempts (yours to keep), more processor profiles (Adyen, Checkout.com, Braintree raw responses), American Express and Discover, a decline scenario in psp-sandbox that uses these codes, dunning emails. Open an issue if you need one of them first.

License

MIT