Payment Gateways

UniPulse supports two payment providers: Stripe for global payments and Paymob for the Middle East & North Africa (MENA) region.

---

Provider Comparison

Feature	Stripe	Paymob
Region	Global	MENA (Egypt, Saudi Arabia, etc.)
Payment methods	Cards, bank transfers, Apple Pay, Google Pay	Cards, mobile wallets (Vodafone Cash, etc.)
Subscriptions	Native subscription management	Manual via API
Webhooks	Comprehensive event system	Payment result callbacks
SDK	stripe npm package	REST API

---

Payment Flow

---

Stripe Integration

API Endpoints

Endpoint	Method	Description
/api/v1/payments/stripe/create-session	POST	Create Stripe Checkout session
/api/v1/payments/stripe/webhook	POST	Handle Stripe webhooks
/api/v1/payments/stripe/portal	POST	Create Stripe Customer Portal link

Webhook Events Handled

Event	Action
invoice.paid	Mark subscription as active, create Transaction
customer.subscription.updated	Update plan, sync feature access
customer.subscription.deleted	Cancel subscription, downgrade to free
payment_intent.payment_failed	Mark subscription as past_due, notify user

Webhook Verification

// Verify Stripe webhook signature
const event = stripe.webhooks.constructEvent(
  req.body,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);

---

Paymob Integration

API Endpoints

Endpoint	Method	Description
/api/v1/payments/paymob/create-session	POST	Create Paymob payment
/api/v1/payments/paymob/callback	POST	Handle Paymob payment callback

Payment Flow

Step	API Call
1. Auth	POST /api/auth/tokens - Get auth token
2. Order	POST /api/ecommerce/orders - Register order
3. Payment key	POST /api/acceptance/payment_keys - Get payment key
4. Redirect	Redirect user to Paymob iframe
5. Callback	Paymob calls webhook with result

---

Database Models

Model	Purpose	Key Fields
Subscription	Active workspace subscription	workspaceId, planId, status, provider, externalId, currentPeriodEnd
Transaction	Individual payment transactions	workspaceId, amount, currency, provider, status, externalId
PaymentMethod	Stored payment methods	workspaceId, provider, type, last4, expiryMonth, expiryYear
Plan	Available subscription plans	name, price, interval, features

---

Subscription Lifecycle

---

Environment Variables

Variable	Provider	Required
STRIPE_SECRET_KEY	Stripe	For Stripe payments
STRIPE_WEBHOOK_SECRET	Stripe	For webhook verification
PAYMOB_API_KEY	Paymob	For Paymob payments

Webhook Security

Always verify webhook signatures before processing. Never trust webhook payloads without signature verification -- they could be forged. Both Stripe and Paymob provide signature verification mechanisms.

---

Cross-Reference

• Webhooks -- webhook processing architecture
• Queue System -- payment-webhook queue
• Schema Overview -- Subscription, Transaction, Plan models
• Auth Flow -- feature gating after plan change