TWIGZ Backend API Documentation

Overview

The Payments API provides secure payment processing through Stripe with automatic marketplace commission handling. It supports PaymentIntents for modern payment flows, handles platform fees, and integrates seamlessly with the order creation system. Location: convex/customers/payments.ts

Payment Flow

Create Payment Intent

Generate Stripe PaymentIntent with cart totals and commission validation

Process Payment

Handle payment on frontend using Stripe Elements or Payment Sheet

Webhook Processing

Automatic order creation via Stripe webhooks on successful payment

Order Fulfillment

Store receives order and begins fulfillment process

Create Payment Intent

Creates a Stripe PaymentIntent for cart checkout with platform commission validation.

customerId

Id<'customers'>

required

Customer ID making the purchase

storeId

Id<'stores'>

required

Store ID receiving the order

subtotal

number

required

Order subtotal before fees

deliveryFee

number

required

Delivery fee amount

platformFee

number

required

Platform commission fee

totalAmount

number

required

Total order amount (subtotal + delivery + platform fee)

currency

string

Currency code (default: “usd”)

cartItems

Array<object>

required

Cart items for payment metadata

deliveryType

'delivery' | 'pickup'

required

Delivery method

deliveryAddress

object

Delivery address details (required for delivery orders)

const paymentSetup = await convex.action(api.customers.payments.createPaymentIntent, {
  customerId: "c123456789",
  storeId: "j123456789",
  subtotal: 45.97,
  deliveryFee: 5.00,
  platformFee: 3.20,
  totalAmount: 54.17,
  currency: "usd",
  cartItems: [
    { 
      productId: "p123456789", 
      productName: "Pizza Margherita", 
      quantity: 2, 
      price: 22.99 
    }
  ],
  deliveryType: "delivery",
  deliveryAddress: {
    fullAddress: "123 Main St, Apt 4B",
    city: "ct123456789",
    area: "ar123456789"
  }
});

const paymentSetup = await convex.action("customers.payments.createPaymentIntent", {
  customerId: "c123456789",
  storeId: "j123456789",
  subtotal: 45.97,
  deliveryFee: 5.00,
  platformFee: 3.20,
  totalAmount: 54.17,
  currency: "usd",
  cartItems: [
    { 
      productId: "p123456789", 
      productName: "Pizza Margherita", 
      quantity: 2, 
      price: 22.99 
    }
  ],
  deliveryType: "delivery"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/action",
    json={
        "path": "customers.payments.createPaymentIntent",
        "args": {
            "customerId": "c123456789",
            "storeId": "j123456789",
            "subtotal": 45.97,
            "deliveryFee": 5.00,
            "platformFee": 3.20,
            "totalAmount": 54.17,
            "currency": "usd",
            "cartItems": [
                {
                    "productId": "p123456789",
                    "productName": "Pizza Margherita",
                    "quantity": 2,
                    "price": 22.99
                }
            ],
            "deliveryType": "delivery"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

payment_setup = response.json()

{
  "clientSecret": "pi_1234567890_secret_abcdefghijklmnop",
  "paymentIntentId": "pi_1234567890",
  "totalAmount": 54.17
}

Get Payment Intent Status

Retrieve the current status of a Stripe PaymentIntent.

paymentIntentId

string

required

Stripe PaymentIntent ID to check

const status = await convex.action(api.customers.payments.getPaymentIntentStatus, {
  paymentIntentId: "pi_123456789"
});

const status = await convex.action("customers.payments.getPaymentIntentStatus", {
  paymentIntentId: "pi_123456789"
});

{
  "status": "succeeded",
  "amount": 54.17,
  "currency": "usd",
  "metadata": {
    "customerId": "c123456789",
    "storeId": "j123456789",
    "deliveryType": "delivery"
  }
}

Cancel Payment Intent

Cancel a Stripe PaymentIntent if user cancels checkout.

paymentIntentId

string

required

Stripe PaymentIntent ID to cancel

const result = await convex.action(api.customers.payments.cancelPaymentIntent, {
  paymentIntentId: "pi_123456789"
});

const result = await convex.action("customers.payments.cancelPaymentIntent", {
  paymentIntentId: "pi_123456789"
});

{
  "status": "canceled"
}

Complete Payment Integration

Here’s a complete payment integration with Stripe Elements:

import React, { useState, useEffect } from 'react';
import { loadStripe } from '@stripe/stripe-js';
import {
  Elements,
  CardElement,
  useStripe,
  useElements
} from '@stripe/react-stripe-js';
import { useAction } from 'convex/react';
import { api } from './convex/_generated/api';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

interface PaymentFormProps {
  customerId: string;
  storeId: string;
  subtotal: number;
  deliveryFee: number;
  platformFee: number;
  totalAmount: number;
  cartItems: any[];
  deliveryType: 'delivery' | 'pickup';
  deliveryAddress?: any;
  onSuccess: (orderId: string) => void;
  onError: (error: string) => void;
}

function PaymentForm({
  customerId,
  storeId,
  subtotal,
  deliveryFee,
  platformFee,
  totalAmount,
  cartItems,
  deliveryType,
  deliveryAddress,
  onSuccess,
  onError
}: PaymentFormProps) {
  const stripe = useStripe();
  const elements = useElements();
  const [processing, setProcessing] = useState(false);
  const [clientSecret, setClientSecret] = useState<string | null>(null);

  const createPaymentIntent = useAction(api.customers.payments.createPaymentIntent);
  const createOrder = useMutation(api.customers.cartToOrder.createOrderFromCart);

  // Create PaymentIntent when component mounts
  useEffect(() => {
    const setupPayment = async () => {
      try {
        const paymentSetup = await createPaymentIntent({
          customerId,
          storeId,
          subtotal,
          deliveryFee,
          platformFee,
          totalAmount,
          currency: "usd",
          cartItems,
          deliveryType,
          deliveryAddress
        });

        setClientSecret(paymentSetup.clientSecret);
      } catch (error) {
        console.error('Payment setup failed:', error);
        onError('Failed to initialize payment');
      }
    };

    setupPayment();
  }, []);

  const handleSubmit = async (event: React.FormEvent) => {
    event.preventDefault();

    if (!stripe || !elements || !clientSecret) {
      return;
    }

    setProcessing(true);

    const card = elements.getElement(CardElement);
    if (!card) {
      setProcessing(false);
      return;
    }

    try {
      // Confirm payment with Stripe
      const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
        payment_method: {
          card: card,
          billing_details: {
            name: 'Customer Name', // You can get this from user profile
          },
        }
      });

      if (error) {
        console.error('Payment failed:', error);
        onError(error.message || 'Payment failed');
      } else if (paymentIntent.status === 'succeeded') {
        // Payment successful - create order
        const order = await createOrder({
          customerId,
          storeId,
          deliveryAddress: deliveryAddress || {
            fullAddress: "Pickup from store",
            city: "" as any,
            area: "" as any,
            phoneNumber: "N/A"
          },
          deliveryType,
          deliveryFee,
          paymentMethod: "card",
          paymentIntentId: paymentIntent.id,
          paymentStatus: "paid"
        });

        onSuccess(order.orderId);
      }
    } catch (error) {
      console.error('Payment processing error:', error);
      onError('Payment processing failed');
    } finally {
      setProcessing(false);
    }
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-6">
      {/* Order Summary */}
      <div className="bg-gray-50 p-4 rounded-lg">
        <h3 className="font-medium text-gray-900 mb-2">Order Summary</h3>
        <div className="space-y-2 text-sm">
          <div className="flex justify-between">
            <span>Subtotal</span>
            <span>${subtotal.toFixed(2)}</span>
          </div>
          <div className="flex justify-between">
            <span>Delivery Fee</span>
            <span>${deliveryFee.toFixed(2)}</span>
          </div>
          <div className="flex justify-between">
            <span>Platform Fee</span>
            <span>${platformFee.toFixed(2)}</span>
          </div>
          <div className="border-t pt-2 flex justify-between font-medium">
            <span>Total</span>
            <span>${totalAmount.toFixed(2)}</span>
          </div>
        </div>
      </div>

      {/* Card Element */}
      <div className="bg-white p-4 border rounded-lg">
        <label className="block text-sm font-medium text-gray-700 mb-2">
          Card Information
        </label>
        <CardElement
          options={{
            style: {
              base: {
                fontSize: '16px',
                color: '#424770',
                '::placeholder': {
                  color: '#aab7c4',
                },
              },
            },
          }}
        />
      </div>

      {/* Submit Button */}
      <button
        type="submit"
        disabled={!stripe || processing}
        className="w-full bg-blue-600 text-white py-3 px-4 rounded-lg hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center"
      >
        {processing ? (
          <>
            <svg className="animate-spin -ml-1 mr-3 h-5 w-5 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
            </svg>
            Processing Payment...
          </>
        ) : (
          `Pay $${totalAmount.toFixed(2)}`
        )}
      </button>
    </form>
  );
}

// Main component with Stripe provider
function CheckoutPage({ orderData }: { orderData: any }) {
  return (
    <Elements stripe={stripePromise}>
      <PaymentForm
        {...orderData}
        onSuccess={(orderId) => {
          console.log('Order created:', orderId);
          // Navigate to success page
        }}
        onError={(error) => {
          console.error('Payment error:', error);
          // Show error message
        }}
      />
    </Elements>
  );
}

export { PaymentForm, CheckoutPage };

import React, { useState } from 'react';
import { Alert } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';
import { useAction, useMutation } from 'convex/react';
import { api } from './convex/_generated/api';

interface PaymentSheetProps {
  customerId: string;
  storeId: string;
  orderData: any;
  onSuccess: (orderId: string) => void;
}

function PaymentSheet({ customerId, storeId, orderData, onSuccess }: PaymentSheetProps) {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const createPaymentIntent = useAction(api.customers.payments.createPaymentIntent);
  const createOrder = useMutation(api.customers.cartToOrder.createOrderFromCart);

  const openPaymentSheet = async () => {
    try {
      setLoading(true);

      // Create PaymentIntent
      const paymentSetup = await createPaymentIntent({
        customerId,
        storeId,
        subtotal: orderData.subtotal,
        deliveryFee: orderData.deliveryFee,
        platformFee: orderData.platformFee,
        totalAmount: orderData.totalAmount,
        cartItems: orderData.cartItems,
        deliveryType: orderData.deliveryType,
        deliveryAddress: orderData.deliveryAddress
      });

      // Initialize payment sheet
      const { error: initError } = await initPaymentSheet({
        merchantDisplayName: 'Twigz Marketplace',
        paymentIntentClientSecret: paymentSetup.clientSecret,
        defaultBillingDetails: {
          name: 'Customer Name',
        },
        allowsDelayedPaymentMethods: false,
      });

      if (initError) {
        Alert.alert('Error', initError.message);
        return;
      }

      // Present payment sheet
      const { error: presentError } = await presentPaymentSheet();

      if (presentError) {
        Alert.alert('Payment Failed', presentError.message);
      } else {
        // Payment successful - create order
        const order = await createOrder({
          customerId,
          storeId,
          deliveryAddress: orderData.deliveryAddress,
          deliveryType: orderData.deliveryType,
          deliveryFee: orderData.deliveryFee,
          paymentMethod: "card",
          paymentIntentId: paymentSetup.paymentIntentId,
          paymentStatus: "paid"
        });

        Alert.alert('Success', 'Payment successful!');
        onSuccess(order.orderId);
      }
    } catch (error) {
      console.error('Payment error:', error);
      Alert.alert('Error', 'Payment processing failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <TouchableOpacity
      onPress={openPaymentSheet}
      disabled={loading}
      style={{
        backgroundColor: loading ? '#ccc' : '#007AFF',
        padding: 16,
        borderRadius: 8,
        alignItems: 'center'
      }}
    >
      <Text style={{ color: 'white', fontSize: 16, fontWeight: 'bold' }}>
        {loading ? 'Processing...' : `Pay $${orderData.totalAmount.toFixed(2)}`}
      </Text>
    </TouchableOpacity>
  );
}

export default PaymentSheet;

Payment Status Monitoring

Monitor payment status for order processing:

import { useState, useEffect } from 'react';
import { useAction } from 'convex/react';
import { api } from './convex/_generated/api';

function usePaymentStatus(paymentIntentId: string | null) {
  const [status, setStatus] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  
  const getPaymentStatus = useAction(api.customers.payments.getPaymentIntentStatus);

  useEffect(() => {
    if (!paymentIntentId) return;

    const checkStatus = async () => {
      setLoading(true);
      try {
        const result = await getPaymentStatus({ paymentIntentId });
        setStatus(result.status);
      } catch (error) {
        console.error('Failed to check payment status:', error);
      } finally {
        setLoading(false);
      }
    };

    // Check immediately
    checkStatus();

    // Poll every 2 seconds for status updates
    const interval = setInterval(checkStatus, 2000);

    // Cleanup
    return () => clearInterval(interval);
  }, [paymentIntentId]);

  return { status, loading };
}

// Usage in component
function OrderStatus({ paymentIntentId }: { paymentIntentId: string }) {
  const { status, loading } = usePaymentStatus(paymentIntentId);

  const getStatusDisplay = () => {
    switch (status) {
      case 'requires_payment_method':
        return { text: 'Waiting for payment', color: 'yellow' };
      case 'requires_confirmation':
        return { text: 'Confirming payment', color: 'blue' };
      case 'processing':
        return { text: 'Processing payment', color: 'blue' };
      case 'succeeded':
        return { text: 'Payment successful', color: 'green' };
      case 'canceled':
        return { text: 'Payment canceled', color: 'gray' };
      case 'requires_action':
        return { text: 'Action required', color: 'orange' };
      default:
        return { text: 'Unknown status', color: 'gray' };
    }
  };

  const statusDisplay = getStatusDisplay();

  return (
    <div className="flex items-center space-x-2">
      <div className={`w-3 h-3 rounded-full ${
        statusDisplay.color === 'green' ? 'bg-green-500' :
        statusDisplay.color === 'blue' ? 'bg-blue-500' :
        statusDisplay.color === 'yellow' ? 'bg-yellow-500' :
        statusDisplay.color === 'orange' ? 'bg-orange-500' :
        'bg-gray-500'
      } ${loading ? 'animate-pulse' : ''}`}></div>
      <span className="text-sm font-medium">{statusDisplay.text}</span>
    </div>
  );
}

Stripe Webhook Integration

The payment system automatically processes orders via webhooks:

// Webhook endpoint: POST /stripe/webhook
// Handles these events:

// 1. payment_intent.succeeded
//    → Creates order from cart
//    → Clears customer cart
//    → Credits store wallet
//    → Sends confirmation notifications

// 2. payment_intent.payment_failed
//    → Logs failure
//    → Sends failure notification
//    → Preserves cart for retry

// 3. payment_intent.canceled
//    → Cleans up resources
//    → Preserves cart
//    → Logs cancellation

Payment Methods

Credit Cards

Supported: Visa, Mastercard, American Express
Processing: Instant via Stripe
Fees: Standard Stripe rates

Debit Cards

Supported: Local and international debit cards
Processing: Instant verification
Fees: Lower processing rates

Digital Wallets

Supported: Apple Pay, Google Pay
Processing: One-touch payments
Fees: Same as card rates

Commission Handling

The payment system automatically handles marketplace commissions:

Error Handling

Payment Intent creation failed

Status Code: 400

{
  "error": "Failed to create payment intent",
  "details": "Invalid amount or currency"
}

Payment declined

Status Code: 402

{
  "error": "Payment declined",
  "code": "card_declined",
  "decline_code": "insufficient_funds"
}

Invalid payment method

Status Code: 400

{
  "error": "Invalid payment method",
  "supported_methods": ["card", "cash", "wallet"]
}

Commission validation failed

Status Code: 400

{
  "error": "Commission validation failed",
  "expected": 3.20,
  "provided": 2.80
}

Security Features

PCI Compliance

All card data is handled by Stripe, ensuring PCI DSS compliance

Fraud Detection

Stripe’s machine learning fraud detection protects against fraudulent transactions

3D Secure

Automatic 3D Secure authentication for enhanced security

Webhook Verification

All webhooks are verified using Stripe signatures

The payment system automatically validates platform commission amounts to ensure consistency between frontend calculations and backend processing.

Always handle payment failures gracefully and provide clear error messages to users. Use Stripe’s test cards for development and testing.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Payments

Overview

Payment Flow

Create Payment Intent

Get Payment Intent Status

Cancel Payment Intent

Complete Payment Integration

Payment Status Monitoring

Stripe Webhook Integration

Payment Methods

Credit Cards

Debit Cards

Digital Wallets

Commission Handling

Error Handling

Security Features

PCI Compliance

Fraud Detection

3D Secure

Webhook Verification

​Overview

​Payment Flow

​Create Payment Intent

​Get Payment Intent Status

​Cancel Payment Intent

​Complete Payment Integration

​Payment Status Monitoring

​Stripe Webhook Integration

​Payment Methods

Credit Cards

Debit Cards

Digital Wallets

​Commission Handling

​Error Handling

​Security Features

PCI Compliance

Fraud Detection

3D Secure

Webhook Verification

Overview

Payment Flow

Create Payment Intent

Get Payment Intent Status

Cancel Payment Intent

Complete Payment Integration

Payment Status Monitoring

Stripe Webhook Integration

Payment Methods

Commission Handling

Error Handling

Security Features