Skip to content

Ways of Paying a Product Refuses

A product can refuse some ways of paying. A basket with that product in it can't be paid for any of those ways, and the shopper is asked to pay another way before any money is held.

The case it was built for is a lottery: a society lottery entry (the DMRT 200 Club) can't legally be bought on credit. It works for anything else a shop needs to keep off a particular card or method, such as American Express on a low-margin product, or pay-later on a gift card.

What can be refused

Each product has an optional paymentRestrictions with three lists. Values are spelt as Stripe spells them:

List Values
Card types (funding) credit, debit, prepaid
Card brands (brands) amex, diners, discover, jcb, unionpay, mastercard, visa, cartes_bancaires, eftpos_au, interac
Payment methods (methods) apple_pay, google_pay, samsung_pay, link, klarna, afterpay_clearpay, paypal, revolut_pay, amazon_pay, bacs_debit, pay_by_bank
  • The restrictions cover every variant of the product.
  • If any line in the basket refuses a way of paying, the whole payment refuses it.
  • Apple Pay, Google Pay and Samsung Pay count as methods even though Stripe reports them as cards. Ticking Apple Pay refuses it whatever card is behind it.
  • Refusing credit cards doesn't refuse pay-later methods (Klarna, Clearpay, PayPal Pay Later), which are credit too. A lottery should refuse both: funding [credit] and methods [klarna, afterpay_clearpay, paypal].
  • If Stripe reports a card's funding as unknown, the card is accepted and a warning is logged.

Setting them

  • Admin: the product's Settings card, under Ways of paying this product refuses (tick boxes).
  • MCP: manageProducts paymentRestrictions, for example {"funding": ["credit"], "methods": ["klarna", "afterpay_clearpay", "paypal"]}. Each list replaces the one before, {} clears them all, and an unknown value is rejected. products get returns them.
  • REST: the product's paymentRestrictions (schema PaymentRestrictions, with enum values).

When the card is checked

Every check reads the products as they are at the time of payment, so a restriction added after the shopper filled their basket still applies.

Checkout Where Money held?
Step checkout on PaymentV2 PaymentV2Adapter.authorisePayment reads the Stripe PaymentMethod the page sent, before the Stripe intent is created No
Single-page (unified) checkout, card On Pay the page makes a Stripe ConfirmationToken from what the shopper entered (only when session.stripe.checkPaymentMethod says the basket has a restricted product) and sends it with start-payment. The token is only read, never used to pay No
Single-page checkout, Apple Pay / Google Pay sheet The sheet's PaymentMethod is sent with start-payment No
Single-page checkout, backstop confirm reads the payment method on the intent. A refused one has its hold released, as for restricted (staff-only) products Released
Legacy step checkout (sites without payment-v2-enabled) Not checked. Switch the site to PaymentV2 before selling a restricted product —

A refusal never takes payment. The shopper sees one sentence naming the product and the way of paying, for example: "200 Club can't be paid for with a credit card. Please use a debit card." The words come from payment.restriction.refused and the payment.restriction.{funding|brand|method}.* labels in messages.properties, with a sentence of its own for credit cards (payment.restriction.refused.funding.credit).

If Stripe can't be asked (an outage), or Stripe.js can't make a confirmation token, the payment goes ahead to the next check rather than failing. The single-page checkout's backstop still runs at confirm.

Saved cards on subscriptions

Sign-up is covered by the checks above. Afterwards a subscriber changes their card in Stripe's billing portal (or from the failed-payment chaser's link), which can't refuse a credit card, so the change is checked when Stripe reports it:

  • customer.updated, when the customer's default card (invoice_settings.default_payment_method) changed. This card pays every subscription of theirs that has no card of its own.
  • customer.subscription.updated, when a subscription's own card (default_payment_method) changed.

When a product of one of the subscriptions it pays refuses the new card, SavedCardRestrictionService either:

  • puts the previous card back, if it is still saved to the customer and none of those products refuses it, or
  • removes the new card from the customer, so a renewal can't be charged to it. The next renewal then fails and the failed-payment chaser asks for a card.

Either way the subscriber gets the card refused email (subscriptionCardRefused): which card, why, and whether their previous card is still being used. Its subject and template are subscriptionCardRefusedCustomerSubject / subscriptionCardRefusedCustomerTemplate in the subscription-emails settings, and it uses the cancellation email's sender and BCC.

customer.updated must be subscribed on both Stripe webhook endpoints (StripeWebhookEvents). The System webhook check flags it until it is.

Classes

Class Module Purpose
PaymentRestrictions common The product's restrictions, the allowed values and the check against a payment method
PaymentMethodFacts common A payment method's type, wallet, funding and brand
PaymentRestrictionService commerce-core Checks an order against a Stripe PaymentMethod or ConfirmationToken
PaymentRefusal commerce-core What was refused and by which product, and the shopper's message
SavedCardRestrictionService commerce-core Puts back or removes a refused saved card
CardRefusedEmailSender commerce-core The card refused email
CustomerUpdatedHandler worker customer.updated webhook
PaymentRestrictionOptions web-admin The admin tick boxes and their labels