updating Checkout docs

prateek-ct · prateek-ct · commit cb18f5b48ad4 · 2025-09-26T10:28:00.000+02:00
diff --git a/README.md b/README.md
@@ -26,6 +26,13 @@ AI-native integrations for modern LLM applications
 - **Features**: MCP server offering 60+ commerce based tools 
 - **Full guide**: [commerce-mcp/essentials-mcp/README.md](commerce-mcp/essentials-mcp/README.md)
 
+### 📦 **Checkout**
+commercetools Checkout integration using Browser SDK
+- **Location**: `checkout/`
+- **Best for**: Prebuilt checkout component including payment integrations
+- **Features**: Full SDK access, type safety, complete control over API calls
+- **Full guide**: [checkout/README.md](checkout/README.md)
+
 ## 🚀 Quick Start
 
 ### For AI/LLM Applications
@@ -42,6 +49,16 @@ cd composable-commerce
 npm install
 ```
 
+### For precomposed Checkout
+```bash
+git clone https://github.com/commercetools/hackathon-starter-kit.git
+cd checkout
+npm run setup
+# Configure .env with your credentials and Checkout Application ID
+npm run build-client && npm run start-client
+npm run start-server
+```
+
 ## 💡 Sample Implementations & Use Cases
 
 ### 🎯 **AI-Powered Commerce Assistant** (Essentials + Developer MCP)
@@ -65,6 +82,18 @@ Traditional service layer applications with:
 
 **Examples**: `composable-commerce/src/examples/`
 
+### 💳 **Checkout Integration Example** (commercetools Checkout)
+Complete React e-commerce application with embedded checkout:
+- **Full Shopping Experience**: Product catalog, cart management, and checkout
+- **Embedded Payments**: Secure payment processing with commercetools Checkout
+- **Multiple Payment Methods**: Credit cards, PayPal, and more
+- **Order Completion**: Success pages and order confirmation
+- **Responsive Design**: Works on desktop and mobile
+- **Real-time Updates**: Cart and checkout state management
+
+**Framework**: `checkout/`
+**Full guide**: [checkout/README.md](checkout-example/README.md)
+
 ## 🔑 Project Setup
 
 ### 1. Create or use a commercetools account
diff --git a/checkout/README.md b/checkout/README.md
@@ -34,62 +34,37 @@ This is the **critical step** - you must set up a Checkout application in Mercha
    - In the left sidebar: Settings → Checkout
    - If you don't see "Checkout", ensure your project has Checkout enabled
 
-3. **Create New Checkout Application**
-   - Click "Create Application"
-   - Fill in application details:
-     - **Name**: "Hackathon Checkout App" (or your preferred name)
-     - **Description**: "Checkout app for hackathon project"
-     - **Application URL**: `http://localhost:3000` (for development)
-     - **Allowed Origins**: `http://localhost:3000, http://localhost:3001`
-
+3. **Configure Checkout Application**
+   - Use sample Checkout application 
+   - Change Origin URLs to "Allow all URLs to communicate to the checkout application" for testing purposes
+  
 4. **Configure Payment Methods**
    - In the Checkout application settings
-   - Add payment methods (Credit Cards, PayPal, etc.)
-   - For testing: Enable "Test Mode" payment processors
+   - Configure Payment Integrations , install Sample payment connector 
+   - Add payment methods (card etc.) and enable them
 
 5. **Copy Application ID**
-   - After creation, copy the **Application ID**
+   - After configuration, copy the **Application ID**
    - You'll need this for your `.env` file
 
-### 3. Payment Integration Setup
-
-#### For Testing (Recommended):
-1. **Enable Test Payment Processors**
-   - In Checkout app settings → Payment Methods
-   - Enable "Test Credit Card Processor"
-   - No additional setup required for testing
-
-#### For Production:
-1. **Configure Real Payment Processors**
-   - Stripe: Add Stripe API keys
-   - PayPal: Configure PayPal credentials
-   - Adyen: Add Adyen credentials
-   - Follow specific integration guides for each processor
-
-2. **Webhook Configuration** (Optional but recommended)
-   - Set webhook URL: `https://yourdomain.com/api/webhook/checkout`
-   - Select events: `checkout.session.completed`, `payment.created`
-
 ## 🛠 Installation & Setup
 
 ### 1. Clone and Install
 
 ```bash
 # From the hackathon-starter-kit root
-cd checkout-example
+cd checkout
 
-# Install server dependencies
-npm install
+# Install server & client dependencies
+npm run setup
 
-# Install client dependencies
-cd client && npm install && cd ..
-```
 
 ### 2. Environment Configuration
 
 ```bash
 # Copy environment template
 cp .env.example .env
+cp /client/.env.example /client/.env
 ```
 
 Edit `.env` with your credentials:
@@ -112,69 +87,32 @@ PORT=3001
 CLIENT_PORT=3000
 ```
 
-**⚠️ Critical**: The `CHECKOUT_APPLICATION_ID` must match the Application ID from your Merchant Center Checkout app.
-
-### 3. Verify Setup
-
-Check if everything is configured correctly:
+Edit client `.env` with your project:
 
-```bash
-# Test API connection
-npm run server
-
-# In another terminal, test the health endpoint
-curl http://localhost:3001/api/health
+```env
+REACT_APP_CTP_PROJECT_KEY=consulting
 ```
 
-Expected response:
-```json
-{
-  "status": "OK",
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "environment": {
-    "projectKey": "your-project-key",
-    "checkoutAppId": "***configured***"
-  }
-}
-```
 
-### 4. Add Sample Products (Optional)
+## 🎯 Running the Application
 
-If your project doesn't have products:
+### Development Mode
 
 ```bash
-# Go to composable-commerce example
-cd ../composable-commerce
-
-# Run the import example to add sample products
-npm run import-product bulk
-
-# Go back to checkout example
-cd ../checkout-example
+# Start server
+npm run start-server
 ```
 
-## 🎯 Running the Application
-
-### Development Mode
-
 ```bash
-# Start both server and client concurrently
-npm run dev
+# Start client
+npm run build-client
+npm run start-client
 ```
 
 This starts:
 - **Backend server**: http://localhost:3001
 - **React client**: http://localhost:3000
 
-### Production Build
-
-```bash
-# Build the client
-npm run build
-
-# Start production server
-npm start
-```
 
 ## 🧪 Testing the Checkout Flow
 
@@ -191,8 +129,7 @@ npm start
 ### 3. Complete Checkout
 - Fill in shipping/billing information
 - Use test card numbers for testing:
-  - **Visa**: 4242424242424242
-  - **Mastercard**: 5555555555554444
+  - **Visa**: 4111111111111111
   - **Expiry**: Any future date
   - **CVV**: Any 3-digit number
 
@@ -201,93 +138,6 @@ npm start
 - Order ID should be displayed
 - Cart should be cleared
 
-## 🔧 Customization
-
-### Styling
-Edit `client/src/App.css` to customize appearance:
-
-```css
-/* Change primary color */
-.btn-primary {
-  background-color: #your-brand-color;
-}
-
-/* Customize checkout appearance */
-.checkout-embedded {
-  /* Custom checkout styling */
-}
-```
-
-### Checkout SDK Configuration
-In `CheckoutPage.js`, customize the SDK loading:
-
-```javascript
-const checkout = await CheckoutAPI.loadCheckout({
-  sessionId: session.sessionId,
-  sessionUrl: session.sessionUrl,
-  locale: 'en', // Change locale
-  appearance: {
-    theme: 'light', // 'light' or 'dark'
-    colorPrimary: '#213547', // Your brand color
-    borderRadius: '8px',
-    fontFamily: 'Arial, sans-serif'
-  }
-});
-```
-
-### Adding Custom Fields
-Extend the checkout session creation in `server.js`:
-
-```javascript
-const checkoutSessionData = {
-  cartId: cartId,
-  countryCode: cart.body.country || 'US',
-  locale: locale,
-  returnUrl: returnUrl,
-  applicationId: process.env.CHECKOUT_APPLICATION_ID,
-  // Add custom fields
-  metadata: {
-    source: 'hackathon-app',
-    campaignId: 'summer2024'
-  }
-};
-```
-
-## 📊 Monitoring & Analytics
-
-### Webhook Events
-The server includes webhook handling for:
-- `CheckoutSessionCompleted`: Payment successful
-- `CheckoutSessionExpired`: Session timed out
-- `PaymentCreated`: Payment object created
-
-### Error Tracking
-Add error tracking service integration:
-
-```javascript
-// In server.js
-const Sentry = require('@sentry/node');
-
-app.use(Sentry.Handlers.errorHandler());
-```
-
-### Order Analytics
-Track successful orders:
-
-```javascript
-// In CheckoutSuccess.js
-useEffect(() => {
-  if (orderId) {
-    // Google Analytics
-    gtag('event', 'purchase', {
-      transaction_id: orderId,
-      value: totalAmount,
-      currency: 'USD'
-    });
-  }
-}, [orderId]);
-```
-
 ## 🚨 Troubleshooting
 
 ### Common Issues
@@ -331,63 +181,10 @@ useEffect(() => {
 - Use valid test card numbers
 - Check payment processor logs in Merchant Center
 
-### Debug Mode
-
-Enable detailed logging:
-
-```bash
-# Set environment variable
-NODE_ENV=development npm run dev
-```
-
-This enables:
-- Console logging for all API calls
-- Debug information in UI
-- Detailed error messages
-
-### API Endpoints for Testing
-
-Test backend functionality directly:
-
-```bash
-# Health check
-curl http://localhost:3001/api/health
-
-# Get products
-curl http://localhost:3001/api/products
-
-# Create test cart
-curl -X POST http://localhost:3001/api/cart/create \
-  -H "Content-Type: application/json" \
-  -d '{"currency": "USD", "country": "US"}'
-```
 
 ## 📖 Additional Resources
 
 ### commercetools Documentation
 - [Checkout Documentation](https://docs.commercetools.com/checkout)
 - [Checkout Browser SDK](https://docs.commercetools.com/checkout/browser-sdk)
-- [Payment Integration Guide](https://docs.commercetools.com/checkout/payment-integrations)
-
-### API References
-- [Platform API](https://docs.commercetools.com/api)
-- [Checkout API](https://docs.commercetools.com/checkout/api)
-
-### Payment Processors
-- [Stripe Integration](https://docs.commercetools.com/checkout/payment-integrations/stripe)
-- [PayPal Integration](https://docs.commercetools.com/checkout/payment-integrations/paypal)
-- [Adyen Integration](https://docs.commercetools.com/checkout/payment-integrations/adyen)
-
-## 🤝 Support
-
-- **Documentation**: [docs.commercetools.com](https://docs.commercetools.com)
-- **Community**: [community.commercetools.com](https://community.commercetools.com)
-- **Support**: [support.commercetools.com](https://support.commercetools.com)
-
-## 📄 License
-
-This example is provided under the MIT License. See LICENSE file for details.
-
----
-
-**Happy coding! 🚀** If you encounter any issues, refer to the troubleshooting section or reach out to the commercetools community.
+- [Payment Connectors](https://docs.commercetools.com/checkout/connectors-and-applications)
