puffin-app/docs/NOCODB_INTEGRATION_GUIDE.md

NocoDB Integration Guide

🎯 Overview

This guide explains how to test and verify the NocoDB integration with Stripe webhooks.

✅ Implementation Summary

Files Created/Modified

New Files:

• server/utils/nocodbClient.js - NocoDB REST API client
• server/utils/nocodbMapper.js - Maps Stripe data to NocoDB format
• docs/NOCODB_INTEGRATION_GUIDE.md - This file

Modified Files:

• server/routes/webhooks.js - Added NocoDB integration
• src/api/nocodbClient.ts - Added createOrder() method
• .env.example - Added NocoDB configuration template

Integration Flow

Stripe Payment Complete
        ↓
Webhook: checkout.session.completed
        ↓
logStripeSessionData() - Comprehensive logging
        ↓
Order.updateStatus() - Update local DB
        ↓
saveOrderToNocoDB() - Save to NocoDB ✨ NEW
        ↓
fulfillOrder() - Create Wren offset
        ↓
updateNocoDBFulfillment() - Update with Wren data ✨ NEW
        ↓
Send receipt email

🔧 Environment Variables

Ensure these are set in server/.env:

# NocoDB Configuration
NOCODB_BASE_URL=https://database.puffinoffset.com
NOCODB_BASE_ID=p11p8be6tzttkhy
NOCODB_API_KEY=Y1thvyr9N53n8WFn7rCgY3ZnLlzPFc4_BdwXCmx-
NOCODB_ORDERS_TABLE_ID=mxusborf4x91e1j

How to find these values:

1. NOCODB_BASE_URL: Your NocoDB instance URL
2. NOCODB_BASE_ID: Go to Base → Copy Base ID
3. NOCODB_API_KEY: User Settings → Tokens → Create Token
4. NOCODB_ORDERS_TABLE_ID: Open table → URL contains table ID

🧪 Testing the Integration

Method 1: Stripe CLI Test (Recommended)

Setup:

# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# In another terminal, start the server
cd server
npm run dev

Trigger Test Payment:

stripe trigger checkout.session.completed

Expected Console Output:

📬 Received webhook: checkout.session.completed

╔════════════════════════════════════════════════════════════════╗
║         STRIPE CHECKOUT SESSION - COMPREHENSIVE DATA          ║
╚════════════════════════════════════════════════════════════════╝
... (all Stripe data logged)

✅ Checkout session completed: cs_test_...
💳 Payment confirmed for order: e0e976e5-...
   Amount: $1649.79

💾 Saving order e0e976e5-... to NocoDB...
✅ Order saved to NocoDB successfully
   NocoDB Record ID: 123
   Order ID: e0e976e5-...
   Customer: Matthew Ciaccio (matt@letsbe.solutions)
   Business: LetsBe Solutions LLC
   Tax ID: eu_vat - FRAB123456789

🌱 Fulfilling order via Wren API...
✅ Order fulfilled successfully
   Wren Order ID: wren_...
   Tons offset: 6.73

💾 Updating NocoDB with fulfillment data...
✅ NocoDB updated with fulfillment data
   Wren Order ID: wren_...
   Status: fulfilled

📧 Receipt email sent to matt@letsbe.solutions

Method 2: Real Test Payment

1. Start Server:

   cd server
   npm run dev
   

2. Make Test Payment:

   • Navigate to checkout
   • Use test card: 4242 4242 4242 4242
   • Fill in test billing information
   • Complete payment

3. Check Logs:

   • Look for NocoDB save confirmation
   • Verify fulfillment update logs

4. Verify in NocoDB:

   • Open NocoDB Orders table
   • Find the new order by orderId
   • Check all fields are populated

🔍 Verification Checklist

After a test payment, verify:

✅ Server Logs

• Comprehensive Stripe data logged
• "Saving order to NocoDB" message
• "Order saved to NocoDB successfully" with Record ID
• "Updating NocoDB with fulfillment data" message
• "NocoDB updated with fulfillment data" message

✅ NocoDB Database

• New record exists in Orders table
• orderId matches Stripe order
• status = "fulfilled" (after Wren fulfillment)
• stripeSessionId populated
• stripePaymentIntent populated
• baseAmount, processingFee, totalAmount correct
• co2Tons, portfolioId from metadata
• customerName, customerEmail populated
• customerPhone populated (if collected)
• businessName populated (if B2B)
• taxIdType and taxIdValue populated (if collected)
• billingLine1, billingCity, billingCountry populated
• wrenOrderId populated after fulfillment
• fulfilledAt timestamp set

✅ Error Handling

Test error scenarios:

• NocoDB temporarily unavailable (should log error but not fail webhook)
• Invalid NocoDB credentials (should skip gracefully)
• Wren API failure (should still save to NocoDB with status='paid')

🐛 Troubleshooting

Issue: "NocoDB not configured"

Cause: Environment variables missing or incorrect

Fix:

# Check environment variables
cd server
cat .env | grep NOCODB

# Ensure all 4 variables are set:
# NOCODB_BASE_URL
# NOCODB_BASE_ID
# NOCODB_API_KEY
# NOCODB_ORDERS_TABLE_ID

Issue: "NocoDB request failed: 401"

Cause: Invalid API key

Fix:

1. Go to NocoDB → User Settings → Tokens
2. Create new token
3. Update NOCODB_API_KEY in .env
4. Restart server

Issue: "NocoDB request failed: 404"

Cause: Incorrect table ID or base ID

Fix:

1. Open your Orders table in NocoDB
2. Check URL: https://nocodb.com/nc/BASE_ID/TABLE_ID
3. Update NOCODB_BASE_ID and NOCODB_ORDERS_TABLE_ID
4. Restart server

Issue: Order saved but fields are null

Cause: Stripe metadata not passed correctly

Fix: Check checkout session creation includes metadata:

const session = await stripe.checkout.sessions.create({
  metadata: {
    baseAmount: '160174',
    processingFee: '4805',
    portfolioId: '37',
    tons: '6.73',
    // Add vessel/trip data if available
  },
  // ... other settings
});

Issue: Business fields not populated

Cause: Stripe checkout not collecting business information

Fix: Update checkout session to collect business details:

const session = await stripe.checkout.sessions.create({
  customer_creation: 'always',
  tax_id_collection: {
    enabled: true,
    required: 'never' // or 'if_supported'
  },
  // ... other settings
});

📊 Database Record Example

Expected NocoDB Record (Business Customer):

{
  "Id": 123,
  "CreatedAt": "2025-11-03T14:30:00.000Z",
  "UpdatedAt": "2025-11-03T14:31:00.000Z",
  "orderId": "e0e976e5-4272-4f5b-a379-c059df6cb5de",
  "status": "fulfilled",
  "source": "web",
  "stripeSessionId": "cs_test_...",
  "stripePaymentIntent": "pi_...",
  "stripeCustomerId": "cus_TM7pU6vRGh0N5N",
  "baseAmount": "160174",
  "processingFee": "4805",
  "totalAmount": "164979",
  "currency": "USD",
  "amountUSD": "164979",
  "paymentMethod": "card",
  "co2Tons": "6.73",
  "portfolioId": "37",
  "portfolioName": null,
  "wrenOrderId": "wren_order_123",
  "certificateUrl": null,
  "fulfilledAt": "2025-11-03T14:31:00.000Z",
  "customerName": "LetsBe Solutions LLC",
  "customerEmail": "matt@letsbe.solutions",
  "customerPhone": "+33633219796",
  "businessName": "LetsBe Solutions LLC",
  "taxIdType": "eu_vat",
  "taxIdValue": "FRAB123456789",
  "billingLine1": "108 Avenue du Trois Septembre",
  "billingLine2": null,
  "billingCity": "Cap-d'Ail",
  "billingState": null,
  "billingPostalCode": "06320",
  "billingCountry": "FR",
  "vesselName": null,
  "imoNumber": null,
  "vesselType": null,
  "vesselLength": null,
  "departurePort": null,
  "arrivalPort": null,
  "distance": null,
  "avgSpeed": null,
  "duration": null,
  "enginePower": null,
  "notes": null
}

🚀 Deployment Checklist

Before deploying to production:

• All NocoDB columns created (42 total)
• Environment variables configured in production .env
• NocoDB API key has proper permissions
• Stripe webhook endpoint configured in Stripe Dashboard
• Webhook signing secret set in production .env
• Test payment processed successfully
• Verify data appears correctly in NocoDB
• Error handling tested (NocoDB unavailable scenario)
• Logs reviewed for any warnings or errors

📝 Next Steps

1. Test with Real Payment:

   • Make a test purchase
   • Verify all fields in NocoDB
   • Check fulfillment updates correctly

2. Enable Additional Features (Optional):

   • Phone number collection in checkout
   • Tax ID collection for B2B customers
   • Vessel/trip metadata for yacht calculations

3. Admin Portal Integration:

   • Connect admin dashboard to NocoDB
   • Display orders table with filters
   • Add order management functionality

4. Monitoring:

   • Set up alerts for failed NocoDB saves
   • Monitor webhook processing times
   • Track fulfillment success rate

📚 Related Documentation

• Schema Reference: docs/NOCODB_SCHEMA.md
• Stripe Webhook Testing: docs/TESTING_STRIPE_WEBHOOK.md
• Integration Summary: docs/STRIPE_INTEGRATION_SUMMARY.md

---

Status: ✅ Integration complete and ready for testing Last Updated: 2025-11-03