Rails E-commerce Backend with Stripe Payments

Project roadmap

1. 01

   Model products, carts and orders

   ~2h

   Create a Rails API-only app with PostgreSQL. Generate Product (name, price in cents, stock), Cart and CartItem, and Order and OrderItem (with the price copied at checkout) plus an order status (pending, paid, failed, refunded) and the Stripe payment intent id. Add associations, validations (prices and quantities above 0) and a unique index on the payment intent id. Seed some products. Done when: the models and seed data work in the Rails console.

2. 02

   Build the cart and checkout

   ~2.5h

   Add endpoints to view the cart, add and remove items, and change quantities, identifying carts by a token. Add POST /checkout, which creates an order from the cart in a transaction: it locks the products (with lock or SELECT FOR UPDATE), checks and reserves stock, and calculates the total on the server. Return clear errors for empty carts and missing stock. Done when: checkout creates a pending order with the right total, and the last item can't be sold twice.

3. 03

   Create Stripe PaymentIntents

   ~2h

   Add the stripe gem with test mode keys from credentials. At checkout, create a PaymentIntent for the order total and currency with the order id in its metadata, using an idempotency key so retries don't create duplicates, and return its client secret for the frontend. Store the intent id on the order. Complete a test payment with a Stripe test card (for example with Stripe's sample frontend or the Stripe CLI). Done when: a test payment appears in the Stripe dashboard linked to the order.

4. 04

   Handle webhooks securely

   ~2.5h

   Add POST /webhooks/stripe that verifies the signature with Stripe::Webhook.construct_event using the raw body and the webhook secret, returning 400 when it fails. On payment_intent.succeeded, mark the order paid; on payment_intent.payment_failed, mark it failed and release the stock. Record processed event ids so repeated deliveries do nothing. Test locally with stripe listen and stripe trigger. Done when: orders update from webhooks, and replayed events change nothing.

5. 05

   Add order history and refunds

   ~2h

   Add GET /orders and GET /orders/{id} for a customer's orders, and an admin POST /orders/{id}/refund that creates a Stripe refund for a paid order, marks it refunded when the charge.refunded webhook arrives, and returns the items to stock. Refuse refunds for unpaid orders. Done when: a refund appears in Stripe and the order and stock update.

6. 06

   Test the payment flows

   ~2.5h

   Write request specs (RSpec or Minitest) with Stripe calls stubbed (for example with WebMock or stripe-ruby-mock) and signed test webhook payloads: checkout totals, stock races (two checkouts for the last item), successful and failed payments, invalid signatures, duplicate webhooks and refunds. Done when: all tests pass without calling Stripe.

Resources

• DocsRails guides: using Rails for API-only applications
• DocsStripe: accept a payment (PaymentIntents)
• DocsStripe: receive webhook events
• DocsStripe: idempotent requests
• DocsStripe CLI
• DocsActive Record: locking