Documentation

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:

ProviderCredentials neededWhere to get them
Stripe (card)Secret key, webhook secretStripe Dashboard → Developers → API keys / Webhooks
PayPalClient ID, client secretdeveloper.paypal.com → your app
SSLCOMMERZStore ID, store passwordSSLCOMMERZ merchant panel
bKashApp key, app secretbKash merchant portal
NagadMerchant ID, private keyNagad merchant onboarding
RazorpayKey ID, key secretdashboard.razorpay.com → API keys
Cash on DeliveryNoneWorks 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

A checkout that “succeeds” but shows unpaid orders usually means the webhook secret is missing or wrong. Check Admin → Payments → provider settings, and the provider dashboard's webhook logs.

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 typeHow it charges
Flat rateOne fixed price per shipment
Weight-basedBase + per-kg, from product weights (brackets, min/max charge)
Subtotal-basedPrice depends on order value (before/after discounts — your choice)
Item-basedFirst-item fee + per-additional-item fee
Free shippingZero above a configurable subtotal threshold
Store pickupCustomer collects — zero by default, optional handling fee
Express / same-dayPremium rate with an order cutoff time and operating days
Manual / customAdmin-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

  1. 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”).
  2. 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.
  3. Rates attach to a method within a zone: amounts, free-shipping thresholds, weight brackets, effective dates, and optional vendor-scoped pricing.
  4. 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.
Mixed-vendor carts get one shipping quote per vendor; the customer selects a method for each. Charges are snapshotted onto the order — later rate edits never change historical orders.

Store pickup

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.

No live courier (DHL/Fedex/Pathao/Steadfast…) integration is pre-wired — connecting one requires real provider credentials and developer work against the adapter interface. Nothing fake is included; see Features & Limitations.