What Is the requires_payment_method Status
A PaymentIntent in Stripe is an object that tracks an intent to collect a payment. The requires_payment_method status means the intent has been created but a payment method has not yet been attached to it — or one was attached but has since been detached.
In plain terms: the server is ready to accept payment, but card details have not been entered yet or were declined.
Why This Status Occurs
There are three main scenarios:
Start of a payment session. Every new PaymentIntent begins with
requires_payment_methodby default. This is normal — the user has not yet filled out the payment form.Card declined by the bank. If the cardholder entered card details but the bank declined the transaction (authorization error, decline), Stripe detaches the payment method and returns the PaymentIntent to
requires_payment_method. The user needs to enter a different card.requires_action session expired. If the cardholder did not complete 3DS authentication and the session timed out, the status may also revert to
requires_payment_method.
What the Cardholder Must Do
The requires_payment_method status is a signal to enter or re-enter card details:
Check if your card was declined. Look at the error message displayed next to the card field.
Enter a different card. If your card was declined, try a different card that has sufficient funds or no restrictions.
Double-check CVV and expiry date. A typo in the three-digit code or an expired card is a common cause of declines.
Confirm your card supports online payments. Some debit cards are blocked for internet transactions by default.
Try a Marix card. If your cards regularly fail, Marix cards are specifically configured for international online payments.
Technical Notes for Developers
- The
requires_payment_methodstatus is a valid starting point in the PaymentIntent lifecycle, not an error. - On bank decline, Stripe automatically detaches the payment method and returns the PaymentIntent to this status.
- Use the
payment_intent.payment_failedwebhook to track this event server-side. - Do not create a new PaymentIntent on every failed attempt — reuse the existing one by attaching a new payment method via
stripe.confirmCardPayment().
FAQ
Does the user need to re-enter their address and other details? It depends on the merchant's form implementation. Typically only the card details need to be re-entered — other fields are preserved.
Why does Stripe detach the payment method on decline? This is by design: on decline, the attached payment method is considered unreliable for this payment. The cardholder must explicitly provide new details.
How many times can different cards be tried? Stripe sets an attempt limit per PaymentIntent (typically up to 5 attach attempts). After that, the object is marked as failed.
Need a card that passes on the first try at international sites? Marix offers virtual cards for online payments with fewer declines.