Payments
What is the Payments Module?
The Charcole payments module adds production-ready payment processing to your application in seconds. When you include it during setup, you get:
- 4 REST endpoints for creating intents, refunding, and checking payment status
- Automatic webhook handling with signature verification and event deduplication
- Zero configuration overhead — everything is environment-driven
- Two first-class providers — Stripe and LemonSqueezy, each fully supported
The module handles the complex parts: adapter switching, signature verification, retry-safe webhook processing, and provider abstraction. You focus on fulfilling orders.
Supported Providers
The module supports two payment providers. Both are equal options — the choice depends on your region and business model.
Stripe
Stripe is the global standard for payment processing.
- Direct API integration with your customers' payment methods
- Your application charges customers' payment methods directly
- Supports most regions and currencies globally
- Best for: SaaS, marketplaces, digital products, and companies with global customers
Important note for Pakistan and similar regions: Stripe does not support PKR payouts to Pakistani bank accounts. If you need to receive payments in Pakistan, use LemonSqueezy instead.
LemonSqueezy
LemonSqueezy operates as a merchant of record. You don't charge customers directly — LemonSqueezy handles the transaction and deposits funds to your account.
- Hosted checkout flow (customers pay on LemonSqueezy's secure page)
- Supports PKR payouts to Pakistani bank accounts
- Excellent for regional SaaS businesses
- Best for: Global + Pakistan/regional payments, companies that need merchant-of-record simplicity
Why we built payments with LemonSqueezy support: Pakistani developers shouldn't have to choose between Stripe's ecosystem and receiving money in their local currency. Both should be possible.
Provider Comparison
| Feature | Stripe | LemonSqueezy |
|---|---|---|
| Payment flow | Frontend JS (client_secret) | Hosted checkout URL |
| Geographic reach | Global | Global |
| PKR payout support | ❌ No | ✅ Yes |
| Best for | Global SaaS, marketplaces | Pakistan, regional businesses |
| Setup complexity | Simple | Simple |
| Webhook events | Rich (20+) | Essential (order, refund, subscription) |
Getting Started
New Charcole Project
When you create a new Charcole project:
npx create-charcole@latest
The CLI will ask: "Include payments module?" Select Yes.
Then choose your provider: Stripe or LemonSqueezy.
Add your provider credentials to .env, and payment endpoints are live immediately at /payments/*.
Existing Project
If you already have a Charcole project and want to add payments:
npm install @charcoles/payments
Then follow the Setup guide. No CLI required — the package works standalone.
Existing Express App (No Charcole)
You can install @charcoles/payments into any Express application:
npm install @charcoles/payments
See Using Without Charcole for setup instructions.
What Comes Next
- Setup — Get payments running in 5 minutes
- Providers — Configure Stripe or LemonSqueezy credentials
- API Endpoints — Reference for all 4 payment endpoints
- Webhooks — Handle payment confirmations reliably
- Environment Variables — Complete reference of all config