<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: AbderrahimBenJazia</title>
    <description>The latest articles on DEV Community by AbderrahimBenJazia (@abderrahimbenjazia).</description>
    <link>https://dev.to/abderrahimbenjazia</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254433%2F8e9ed43b-9429-4f8c-a3f7-6bc3dd5368d2.png</url>
      <title>DEV Community: AbderrahimBenJazia</title>
      <link>https://dev.to/abderrahimbenjazia</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/abderrahimbenjazia"/>
    <language>en</language>
    <item>
      <title>Stripe doesn't tell you which card declines to retry, so we open-sourced the rules</title>
      <dc:creator>AbderrahimBenJazia</dc:creator>
      <pubDate>Thu, 19 Nov 2026 19:56:47 +0000</pubDate>
      <link>https://dev.to/abderrahimbenjazia/stripe-doesnt-tell-you-which-card-declines-to-retry-so-we-open-sourced-the-rules-260p</link>
      <guid>https://dev.to/abderrahimbenjazia/stripe-doesnt-tell-you-which-card-declines-to-retry-so-we-open-sourced-the-rules-260p</guid>
      <description>&lt;p&gt;If you run a subscription business on Stripe, you've seen this in your logs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"code"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"card_declined"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"decline_code"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"do_not_honor"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Your card was declined."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And then you have to decide three things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Should I retry this card?&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Who can actually fix it?&lt;/strong&gt; The bank, the customer, or me?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What do I tell the customer?&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Stripe's &lt;a href="https://docs.stripe.com/declines/codes" rel="noopener noreferrer"&gt;decline code reference&lt;/a&gt; lists the codes and a one-line next step for each. What it doesn't give you is a hard/soft split you can code against, or customer-facing copy that's safe to show. So every team ends up writing its own &lt;code&gt;switch (decline_code)&lt;/code&gt;, usually with a few wrong branches.&lt;/p&gt;

&lt;p&gt;We wrote ours while building failed-payment recovery for &lt;a href="https://flow-mrr.com" rel="noopener noreferrer"&gt;FlowMRR&lt;/a&gt;, then pulled it out into a small MIT package: &lt;strong&gt;&lt;a href="https://www.npmjs.com/package/stripe-declines" rel="noopener noreferrer"&gt;stripe-declines&lt;/a&gt;&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install stripe-declines
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No dependencies, ESM and CommonJS, TypeScript types, Node 18+.&lt;/p&gt;

&lt;h2&gt;
  
  
  One call, three answers
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;explain&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe-declines"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"do_not_honor"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;retry&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;    &lt;span class="c1"&gt;// "likely"  (likely | maybe | no)&lt;/span&gt;
&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fixer&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;    &lt;span class="c1"&gt;// "bank"    (bank | customer | you)&lt;/span&gt;
&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;   &lt;span class="c1"&gt;// "Retry on Stripe's schedule. Suggest the customer calls their bank if it fails twice."&lt;/span&gt;
&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// "Your bank declined this payment. This is often temporary: ..."&lt;/span&gt;
&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;    &lt;span class="c1"&gt;// a full email with {name}, {product}, {link}, {company}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All 51 codes are grouped into eight categories, and each category has a different playbook:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Category&lt;/th&gt;
&lt;th&gt;What happened&lt;/th&gt;
&lt;th&gt;Retry the same card?&lt;/th&gt;
&lt;th&gt;Who fixes it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;soft&lt;/td&gt;
&lt;td&gt;Bank refused, no lasting reason&lt;/td&gt;
&lt;td&gt;Often succeeds later&lt;/td&gt;
&lt;td&gt;Bank&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;funds&lt;/td&gt;
&lt;td&gt;Not enough balance or credit&lt;/td&gt;
&lt;td&gt;Often, a few days later&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;card&lt;/td&gt;
&lt;td&gt;Card is dead or wrong&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;limit&lt;/td&gt;
&lt;td&gt;A card limit was hit&lt;/td&gt;
&lt;td&gt;No, until it changes&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;restricted&lt;/td&gt;
&lt;td&gt;Card can't be used for this payment&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;auth&lt;/td&gt;
&lt;td&gt;Bank wants 3DS / SCA&lt;/td&gt;
&lt;td&gt;Once they authenticate&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;fraud&lt;/td&gt;
&lt;td&gt;Issuer blocked the card&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;td&gt;Customer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;merchant&lt;/td&gt;
&lt;td&gt;Something on your side&lt;/td&gt;
&lt;td&gt;Once you fix it&lt;/td&gt;
&lt;td&gt;You&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  It reads whatever you paste
&lt;/h2&gt;

&lt;p&gt;In practice you rarely have a clean code. You have an error object, a Charge, a webhook payload, or a log line someone pasted into Slack. &lt;code&gt;explain()&lt;/code&gt; takes any of them:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Your card has insufficient funds."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;            &lt;span class="c1"&gt;// "insufficient_funds"&lt;/span&gt;
&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Votre carte a des fonds insuffisants."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"fr"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;   &lt;span class="c1"&gt;// "insufficient_funds"&lt;/span&gt;
&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"{ code: 'card_declined', decline_code: 'incorrect_cvc' }"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Node dump&lt;/span&gt;
&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"{'decline_code': 'expired_card'}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;              &lt;span class="c1"&gt;// Python dump&lt;/span&gt;
&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"hello"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// null&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;JSON, and objects as dumped by Node, Python, PHP or Ruby all work. Missing or non-string input returns &lt;code&gt;null&lt;/code&gt; instead of throwing, so this is safe at checkout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;customerMessage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe-declines"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="nf"&gt;customerMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;decline_code&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;locale&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="n"&gt;genericMessage&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The three traps
&lt;/h2&gt;

&lt;p&gt;These are the cases where most hand-written dunning logic gives the wrong advice.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. &lt;code&gt;advice_code&lt;/code&gt; beats the decline code
&lt;/h3&gt;

&lt;p&gt;On many declines, Stripe now sends an &lt;code&gt;advice_code&lt;/code&gt;: &lt;code&gt;do_not_try_again&lt;/code&gt;, &lt;code&gt;try_again_later&lt;/code&gt; or &lt;code&gt;confirm_card_data&lt;/code&gt;. When it's there, it should decide the retry, whatever the decline code says.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;explain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'{"decline_code":"do_not_honor","advice_code":"do_not_try_again"}'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// { code: "do_not_honor", retry: "no", retrySource: "advice_code", ... }&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A plain &lt;code&gt;do_not_honor&lt;/code&gt; is usually worth a later retry. A &lt;code&gt;do_not_honor&lt;/code&gt; with &lt;code&gt;do_not_try_again&lt;/code&gt; is not.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. A Radar block looks like a decline, but isn't one
&lt;/h3&gt;

&lt;p&gt;When Radar blocks a payment, the charge still says &lt;code&gt;failure_code: "card_declined"&lt;/code&gt;. If you map that to "soft decline, retry later", you'll keep hammering a payment Stripe already decided not to send to the bank.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;findCode&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;findNote&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe-declines"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;charge&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'{"failure_code":"card_declined","outcome":{"reason":"highest_risk_level","type":"blocked"}}'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nf"&gt;findCode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;charge&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;        &lt;span class="c1"&gt;// null, not a bank decline&lt;/span&gt;
&lt;span class="nf"&gt;findNote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;charge&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;term&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;  &lt;span class="c1"&gt;// "highest_risk_level"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  3. Never tell the customer their card was reported stolen
&lt;/h3&gt;

&lt;p&gt;For &lt;code&gt;lost_card&lt;/code&gt;, &lt;code&gt;stolen_card&lt;/code&gt;, &lt;code&gt;pickup_card&lt;/code&gt; and &lt;code&gt;fraudulent&lt;/code&gt;, Stripe asks you to present the failure like a generic decline. You don't have to stay silent, though: asking for another card is fine, and it still recovers real customers who were flagged by mistake.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;customerMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"stolen_card"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// "Your card was declined. Please pay with another card, or contact your bank for details."&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The package's tests enforce this: no customer message or email names the real reason for those codes, and none promises a retry that the code's verdict says won't happen.&lt;/p&gt;

&lt;h2&gt;
  
  
  From the terminal
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npx stripe-declines do_not_honor
npx stripe-declines insufficient_funds --customer
npx stripe-declines &lt;span class="s2"&gt;"Your card has insufficient funds."&lt;/span&gt; --lang fr --email

&lt;span class="c"&gt;# explain declines as they happen&lt;/span&gt;
stripe logs tail &lt;span class="o"&gt;|&lt;/span&gt; grep decline_code &lt;span class="o"&gt;|&lt;/span&gt; npx stripe-declines --json
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Not using JavaScript?
&lt;/h2&gt;

&lt;p&gt;The data ships as plain JSON, so any language can read it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;codes&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe-declines/codes.json"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It holds the eight categories, the 51 codes (50 decline codes plus &lt;code&gt;card_declined&lt;/code&gt;, which people paste all the time), four notes for Radar and Adaptive Acceptance blocks, and a &lt;code&gt;reviewed&lt;/code&gt; date for the last check against Stripe's reference.&lt;/p&gt;

&lt;h2&gt;
  
  
  Just want to look up a code?
&lt;/h2&gt;

&lt;p&gt;There's a free web version of the same rules, no signup and no Stripe key: the &lt;a href="https://flow-mrr.com/en/tools/card-decline" rel="noopener noreferrer"&gt;Card Decline Decoder&lt;/a&gt;. Paste a code or a whole error and you get the meaning, the retry verdict and a customer email.&lt;/p&gt;

&lt;h2&gt;
  
  
  Contributions welcome
&lt;/h2&gt;

&lt;p&gt;Decline handling is full of folklore. If you think a verdict is wrong, open an issue with the Stripe documentation that backs it: &lt;a href="https://github.com/flowmrr/stripe-declines" rel="noopener noreferrer"&gt;github.com/flowmrr/stripe-declines&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;How do you handle declines today: a hand-written map, Smart Retries only, or a dunning tool? I'm curious which codes cause you the most trouble.&lt;/p&gt;

</description>
      <category>stripe</category>
      <category>javascript</category>
      <category>saas</category>
      <category>opensource</category>
    </item>
  </channel>
</rss>
