All articles

Commerce Stripe and Stripe Link: when a paid order stays in draft

With Commerce Stripe 2.2.1, a payment funded through Stripe Link can come back as a card payment method whose brand is "link". Commerce's card type mapping doesn't know that brand and throws HardDeclineException, but by then Stripe has already confirmed the payment, so the customer is charged while the Drupal order stays in draft. The fix a teammate shipped is a small Composer patch: catch the exception around the card-detail mapping, save the payment method without card details, mark it non-reusable and log a warning.

What the failure looks like

The setup is a group of nonprofit membership sites on one Drupal distribution, taking payments through Drupal Commerce and the contributed Commerce Stripe module. Stripe can offer Link, its saved-details wallet, alongside ordinary card entry. Most Link payments behave like any other card payment.

Some don't. When the money behind a Link payment came from somewhere other than a card (the team's patch notes Link Instant Bank Payments as an example), Stripe still described the payment method as a card, with "link" as its brand. Commerce Stripe copies the card details onto the Drupal payment method after the payment succeeds, and part of that is translating Stripe's brand into one of Commerce's credit card types: Visa, Mastercard, American Express and so on. "link" is not on that list, and the mapping's answer to an unknown brand is to throw HardDeclineException.

A hard decline is the right exception before a payment. It tells checkout that the card can't be used and the customer should try another. Thrown after Stripe has confirmed the payment, it does something much worse: checkout stops, the order never leaves the draft state, and the customer sees an error for a payment that went through. From the outside it looks like a decline; in Stripe's dashboard it looks like a success.

Why it is easy to miss

Three things hide this bug. Testing with Stripe's test card numbers always returns a real card brand, so the unknown-brand path never runs in development. The exception class names a normal, expected outcome, so a log line saying "hard decline" reads as a customer problem rather than a code problem. And the failure only appears for one funding route of one wallet, so most payments, including most Link payments, succeed.

The signal that gives it away is a mismatch between the two systems: a succeeded payment in Stripe with no matching placed order in Drupal. If you take payments with Commerce Stripe, comparing the two for the last few weeks is a cheap check.

How the team's patch handles the unknown brand

The mapping happens in two places in Commerce Stripe: the card payment method type plugin, which updates a payment method from Stripe's data, and the gateway plugin, which fills in a new payment method's details after the payment. The team's change wraps the card-detail block in both places in a try/catch for HardDeclineException. When it is caught, the payment method is saved without card type, last four digits or expiry, it is marked as non-reusable, and a warning is logged with the brand and the Stripe payment method id. The rest of the flow carries on: the remote id is set, the customer is attached, and the order completes.

Two of those decisions are worth calling out.

Non-reusable, not "unknown card". Saving the method as reusable would offer it to the customer at their next checkout as a stored card with no type, number or expiry, which Commerce and the customer would both struggle with. A non-reusable method records how this order was paid and then gets out of the way.

Log a warning, don't swallow it. The catch exists because the payment already happened, not because an unknown brand is fine. The warning names the brand, so if Stripe starts returning another one, it shows up in the logs as a new value rather than as another wave of stuck orders.

The general shape, if you are writing this kind of code yourself, is to make the mapping total once money has moved: an unknown value becomes "no detail" rather than an exception.

<?php

/**
 * Maps a Stripe card brand to a Commerce card type, or NULL if unknown.
 */
function example_card_type(string $brand): ?string {
  $types = [
    'visa' => 'visa',
    'mastercard' => 'mastercard',
    'amex' => 'amex',
    'discover' => 'discover',
    'jcb' => 'jcb',
    'diners' => 'dinersclub',
    'unionpay' => 'unionpay',
  ];
  return $types[$brand] ?? NULL;
}

$type = example_card_type($card->brand);
if ($type === NULL) {
  // The payment has succeeded; record it without card details.
  $payment_method->setReusable(FALSE);
  $logger->warning('Unsupported card brand @brand', ['@brand' => $card->brand]);
}
else {
  $payment_method->set('card_type', $type);
}

Why a Composer patch rather than an override

The mapping is a static method called from inside the module's plugins, so there is no service to decorate and no event to subscribe to at the right moment. Overriding the plugin classes would copy far more of the module into the codebase than the fix needs, and it would drift from upstream with every release. A patch file, applied by cweagans/composer-patches, keeps the change to the lines that matter and makes the dependency on the module version visible:

"extra": {
  "patches": {
    "drupal/commerce_stripe": {
      "2.2.1: tolerate the Stripe card brand 'link' after payment": "patches/commerce-stripe-link-brand.patch"
    }
  }
}

Putting the version in the description is a small habit I like. When someone updates the module, the patch either fails to apply, which is loud, or applies to a version it wasn't written for, and the description tells them to check whether upstream has fixed it. Before carrying a patch like this, search the Commerce Stripe issue queue on drupal.org: if an issue exists, link it in the description; if not, it is worth opening one.

What to do about orders already stuck

The patch stops new orders getting stuck; it does nothing for ones that already are. Those need finding (succeeded Stripe payments against draft orders), and then a decision per order: place it by hand with a payment record, or refund it. Which is right depends on what the order bought, and either way it means checking that the customer didn't pay again after seeing the error.

Key takeaways

  • Commerce Stripe can throw HardDeclineException for the card brand "link" after Stripe has already confirmed the payment, leaving the order in draft.
  • An exception that means "decline" is only safe before money moves; after that, map unknown values to "no detail" and keep going.
  • Store a payment method you can't fully describe as non-reusable, so it never appears as a broken saved card.
  • Log the unexpected value, so the next new brand is a log entry rather than another set of stuck orders.
  • Compare succeeded payments in Stripe with placed orders in Drupal to find orders this kind of bug has already stranded.