Developer Docs

v2.0

Webhooks, SDKs, and integration guides for satellite apps

Complete Developer Guide (PDF)

Download the full API reference, webhook payloads, SDK examples & integration checklist — perfect for uploading to your vibe coding platform.

Data Ownership Model

YOUR app owns the product catalog. SynapSaaS pulls products FROM your app so it knows what to bill and invoice. Create and manage products in YOUR database, then expose GET /api/products so SynapSaaS can sync them.

⚠️ The #1 Mistake: Don't create products on SynapSaaS

SynapSaaS works like Stripe — you store products in your own database, and when a user clicks "Buy", you send the amount to SynapSaaS. There is no product CRUD API on SynapSaaS.

Your App's DB → Products table (you create and manage this)

├── Pro Plan ($10/mo)

├── Basic Plan ($5/mo)

└── Enterprise ($50/mo)

At checkout → POST /api/initiatePayment

{ amount: 10, currency: "USD", item_name: "Pro Plan" }

✅ What SynapSaaS Does

• Processes payments (PayFast, Stripe, Paystack)
• Manages subscription lifecycle
• Generates and sends invoices
• Sends webhook notifications
• Tracks transaction history

❌ What SynapSaaS Does NOT Do

• No product CRUD API — cannot create/read/update/delete products
• No product catalog — your app stores and serves its own
• No user authentication — your app manages its own users
• No frontend UI — you build your own checkout

✅ Correct: YOUR app does this

• Creates Product/Plan entity in your DB
• Builds pricing page from your DB
• Stores subscription status in your DB
• Sends amount to SynapSaaS at payment time

❌ Wrong: Don't do this

• Don't call SynapSaaS to "create products"
• Don't call SynapSaaS to "list products"
• Don't store product data on SynapSaaS
• Don't modify SynapSaaS product records

Think of it like Stripe: you store products in your database, display them on your pricing page, and when a user clicks "Buy" you send the amount to the payment processor. SynapSaaS works the exact same way.

Supported Currencies

ZAR

USD

EUR

GBP

Supported Transaction Types

purchase

upgrade

downgrade

renewal

cancellation

refund

addon

Payment Gateways

payfast

stripe

paystack

Sandbox / Live Mode Toggle: SynapSaaS has a global sandbox toggle (Settings → Payment Gateway). When sandbox is ON, ALL payment initiations across ALL satellites use test/sandbox credentials. No real money is charged. This applies to PayFast (sandbox environment), Stripe (test API keys), and PayStack (test API keys). Always switch back to Live mode for production.

Gateway-Specific Webhook Endpoints

PayFast (ITN)

SynapSaaS auto-configures the notify_url. PayFast sends server-to-server notifications (ITN) when payments complete.

/api/functions/payfastITN

Stripe (Webhooks)

Configure this URL in your Stripe Dashboard → Webhooks. Listen for checkout.session.completed and payment_intent.payment_failed.

/api/functions/stripeWebhook

PayStack (Webhooks)

Configure this URL in your PayStack Dashboard → Settings → API Keys & Webhooks. Listen for charge.success and charge.failed.

/api/functions/paystackWebhook

Required Environment Variables

SYNAPSAAS_API_KEY=sat_xxxxx...
SYNAPSAAS_SATELLITE_ID=<your satellite_platform_id>
SYNAPSAAS_WEBHOOK_SECRET=whsec_xxxxx...

# ⚠️ Use the satellite webhook_secret (whsec_xxxx...)
# NOT the endpoint secret (whsec_ep_xxxx...)

The satellite_platform_id is required in every API call. Find it in your Satellite Dashboard.

Gateway Credentials Required

Gateway	Live Keys	Sandbox/Test Keys
PayFast	merchant_id, merchant_key, passphrase	sandbox_merchant_id, sandbox_merchant_key (defaults: 10000100 / 46f0cd694581a)
Stripe	sk_live_..., whsec_... (webhook signing)	sk_test_...
PayStack	sk_live_...	sk_test_...