Payments & Shipping
How money comes in and how orders go out. Both systems are admin-controlled and support multiple providers at once.
On this page
Payment gateways
Admin → Payments. SaleX ships with these providers — each needs credentials before it appears at checkout:
| Provider | Credentials needed | Where to get them |
|---|---|---|
| Stripe (card) | Secret key, webhook secret | Stripe Dashboard → Developers → API keys / Webhooks |
| PayPal | Client ID, client secret | developer.paypal.com → your app |
| SSLCOMMERZ | Store ID, store password | SSLCOMMERZ merchant panel |
| bKash | App key, app secret | bKash merchant portal |
| Nagad | Merchant ID, private key | Nagad merchant onboarding |
| Razorpay | Key ID, key secret | dashboard.razorpay.com → API keys |
| Cash on Delivery | None | Works out of the box when enabled |
Each gateway has a TEST/LIVE mode switch in the admin settings, with separate credential slots per mode. Credentials can be entered in the admin panel (recommended — takes effect immediately) or via .env as fallbacks.
Test vs live credentials
- Test mode uses sandbox accounts: Stripe test cards (e.g. the classic 4242… card), PayPal sandbox, etc. No real money moves. Use it during setup.
- Live mode requires provider activation (bank details, KYC). Only switch after successful end-to-end tests.
- Webhooks: each provider has a webhook URL to configure on the provider's side. Copy the provider's signing secret back into SaleX — webhooks confirm payments even if the customer closes the browser mid-redirect.
Shipping engine
Admin → Shipping. The engine computes real quotes at checkout — per vendor, per delivery zone — and stores an immutable snapshot of the charge on each order.
Shipping methods
Enable any combination; all can coexist:
| Method type | How it charges |
|---|---|
| Flat rate | One fixed price per shipment |
| Weight-based | Base + per-kg, from product weights (brackets, min/max charge) |
| Subtotal-based | Price depends on order value (before/after discounts — your choice) |
| Item-based | First-item fee + per-additional-item fee |
| Free shipping | Zero above a configurable subtotal threshold |
| Store pickup | Customer collects — zero by default, optional handling fee |
| Express / same-day | Premium rate with an order cutoff time and operating days |
| Manual / custom | Admin-applied rates for special cases (permission-controlled) |
Methods can be customer-selectable or auto-assigned, restricted by zone or vendor, and reordered for display priority.
Zones & rates
- Zones describe WHERE you deliver: by country, state/region, city, or postcode. Create a broad fallback zone (e.g. “United States”), then more specific ones (“East Coast”, “NYC Metro”).
- Precedence is automatic and deterministic: the most specific matching zone wins; ties break by priority. If nothing matches, checkout clearly says delivery is unavailable for those items — it never silently picks a random zone.
- Rates attach to a method within a zone: amounts, free-shipping thresholds, weight brackets, effective dates, and optional vendor-scoped pricing.
- Use the built-in test calculator (Admin → Shipping → Calculator) to preview: enter a destination and cart, see the matched zone, eligible methods, formulas, and final totals.
Store pickup
- Enable pickup per vendor (admin policy) or globally.
- Vendors with permission create pickup locations: name, address, opening hours, instructions.
- At checkout the customer picks a location and sees its hours/instructions; the charge is zero unless you configure a handling fee.
- Vendor workflow: accept → ready for pickup → customer collects (timestamp recorded).
Third-party couriers
SaleX includes a provider adapter interface (serviceability, quotes, booking, labels, tracking, webhooks) ready for courier integrations. The distribution ships with the manual workflow: vendors/admins set tracking numbers and carriers by hand, and shipment status flows work fully without any courier API.