How can I update a Stripe Checkout failed payment to 'failed' in Rails without using webhooks?

Stripe Checkout doesn't offer a built-in way to redirect users to a separate failure route when a payment fails. The only URLs you can configure when creating a Checkout Session are:

• success_url: Where the user is redirected after a successful payment.
• cancel_url: Where the user is sent if they cancel out of the checkout flow.

The cancel_url is intended for users who exit the flow (for example, by clicking a "Cancel" button), not for handling payment failures such as a declined card.

In your case, when a card is declined (as with the insufficient funds test card), Stripe shows the error message directly on the Checkout page instead of redirecting. Because the failure isn’t considered a “cancel” event, the cancel_url isn’t used.

Updating Payment Status Without Webhooks

Unfortunately, without webhooks there isn’t a reliable alternative to update your internal payment status (from pending to failed) in real time. While you could try to poll or retrieve the Checkout Session or PaymentIntent after redirection, there are a few challenges:

• Asynchronous State Changes: The Checkout Session only returns the initial information when created. The PaymentIntent state (which reflects the failure) is updated asynchronously.
• User Flow Uncertainty: Users may not always leave the Checkout page (especially if the failure message is displayed there), so you can’t guarantee they’ll hit a URL in your application where you could trigger an update.
• Reliability: Polling the PaymentIntent status from your frontend or backend can be unreliable and may not capture the exact moment the payment fails.

Recommended Approach – Use Webhooks

The established and recommended solution is to implement a webhook endpoint. By using webhooks, you can receive asynchronous events from Stripe — for example, when a PaymentIntent fails (via the event type payment_intent.payment_failed). When you receive such an event, you can update your internal database to mark the payment as failed. This method is reliable, event-driven, and decoupled from the user’s navigation.

Here’s a simplified flow with webhooks:

1. Create the Checkout Session:
   Your existing code to create the Checkout session (with success_url and cancel_url) stays the same.

2. Implement a Webhook Endpoint:
   Create an endpoint on your server to handle events from Stripe. For example, using Ruby on Rails:

   RUBYCopied
   # config/routes.rb
   post 'stripe/webhook', to: 'stripe#webhook'

   RUBYCopied
   # app/controllers/stripe_controller.rb
   class StripeController < ApplicationController
     # Disable CSRF for the webhook endpoint
     skip_before_action :verify_authenticity_token
   
     def webhook
       payload = request.body.read
       sig_header = request.env['HTTP_STRIPE_SIGNATURE']
       webhook_secret = Rails.application.credentials.stripe[:webhook_secret]
   
       begin
         event = Stripe::Webhook.construct_event(payload, sig_header, webhook_secret)
       rescue JSON::ParserError => e
         # Invalid payload
         render status: 400, json: { error: 'Invalid payload' } and return
       rescue Stripe::SignatureVerificationError => e
         # Invalid signature
         render status: 400, json: { error: 'Invalid signature' } and return
       end
   
       # Handle the event
       case event.type
       when 'payment_intent.payment_failed'
         payment_intent = event.data.object
         # Find your payment by payment_intent id and update status
         payment = Payment.find_by(payment_intent_id: payment_intent.id)
         payment&.update(status: 'failed')
       when 'payment_intent.succeeded'
         payment_intent = event.data.object
         # Update your records accordingly
         payment = Payment.find_by(payment_intent_id: payment_intent.id)
         payment&.update(status: 'succeeded')
       end
   
       render json: { message: 'success' }
     end
   end

3. Update Your Payment Record:
   As soon as the payment_intent.payment_failed event is received, update your Payment record status from pending to failed.

Conclusion

Without using webhooks, there's no native way in Stripe Checkout to redirect a user to a unique failure URL or update your internal records reliably when a payment fails. Your safest and most reliable approach is to use webhooks to listen for events like payment_intent.payment_failed and update your database accordingly.

If you have any follow-up questions about integrating webhooks or handling these events, feel free to ask!