OpenCart · Store Extension · PHP 7.4+
Overview
The SabPaisa OpenCart extension bundles the SabPaisa PHP SDK inside the package (no Composer required) and gives your store all five SabPaisa flows from the admin panel — with no code changes. There are two packages, one per OpenCart major version.
| Package | OpenCart version | Install path |
|---|---|---|
| opencart-3.x/upload/ | 3.0.x | merges into admin/ + catalog/ + system/ |
| opencart-4.x/extension/sabpaisa/ | 4.0.x | drop into extension/sabpaisa/ |
Hosted Checkout
Cards, UPI, net banking, wallets via SabPaisa's hosted page
Native UPI QR
UPI QR on your own page (S2S) — falls back to hosted if S2S is off
No Composer
Files only — copy in, click Install in the admin panel
Callback + Webhook
Server-side re-enquiry and verified server-push for async UPI
Admin Re-check
One-click reconcile of a stuck order from the admin panel
Refunds in Admin
Full or partial refunds from the order page — no extra setup
Prerequisites
| Requirement | Minimum |
|---|---|
| PHP | 7.4+ with curl + json extensions |
| OpenCart | 3.0.x or 4.0.x |
| SabPaisa Merchant Account | dashboard.sabpaisa.in |
system/library/sabpaisa/src/ with a standalone PSR-4 autoload.php (prefix SabPaisa\). It only needs PHP's curl and json extensions — there is no Composer step.Step 1 — Install the Extension
OpenCart 3.x
Copy the contents of opencart-3.x/upload/ into your OpenCart root (merges into the existing admin/, catalog/, system/ directories).
Log into the admin panel, go to Extensions → Extensions, and choose Payments in the type dropdown.
Find SabPaisa and click the green + to install.
Click the blue pencil to edit; fill credentials, set Status → Enabled, choose your order-status mapping, and Save.
OpenCart 4.x
Copy opencart-4.x/extension/sabpaisa/ into your store's extension/ directory so you have extension/sabpaisa/. (Or zip the folder with sabpaisa/ as the top-level entry and upload via the Extension Installer.)
Log into the admin panel, go to Extensions → Extensions, and choose Payments in the type dropdown.
Find SabPaisa and click the green + to install.
Click the blue pencil to edit; fill credentials, set Status → Enabled, choose your order-status mapping, and Save.
Step 2 — Enter Your Credentials
All credentials are entered in the admin settings page (Extensions → Extensions → Payments → SabPaisa → Edit) — nothing is hardcoded.
| Admin field | Used by the extension as |
|---|---|
| API Key | X-Api-Key header on all outbound calls (sp_…) |
| Secret Key | HMAC-SHA256 signing key for checksums (sec_…) |
| Merchant ID | request body + X-Merchant-Id header |
| Webhook Secret | verifies X-SabPaisa-Signature on webhooks (different from the secret key) |
| Environment | Staging (test) / Production (live) — selects the base URL |
| Completed / Failed / Pending Status | OpenCart order statuses applied from SabPaisa's reported state |
secretKey (sec_…) and a legacy hmac_api_key (64-char hex). The SDK signs with secretKey — putting hmac_api_key in the Secret Key field produces INVALID_SIGNATURE on every transaction.Step 3 — Configure the Webhook
Enter a Webhook Secret in the admin form (issued by SabPaisa, different from the API secret key), then register the matching webhook URL in your SabPaisa dashboard. The route differs by OpenCart major version:
1OpenCart 3.x:
2https://yourshop.com/index.php?route=extension/payment/sabpaisa/webhook
3
4OpenCart 4.x:
5https://yourshop.com/index.php?route=extension/sabpaisa/payment/sabpaisa.webhookSabPaisa POSTs each event with X-SabPaisa-Signature: <timestamp>.<base64sig>. The extension verifies the HMAC over <timestamp>.<rawBody>, enforces a 300-second replay window, and compares constant-time — returning 401 on a bad/expired signature and 200 on an unknown order (to stop endless retries).
Step 4 — Test & Go Live
Keep Environment on Staging (test) and place a small order, choosing SabPaisa at checkout.
Verify the order reaches your mapped Completed status in Sales → Orders.
Switch Environment to Production (live) and rotate to your live credential set (staging and production credentials differ).
Payment Flows
Flow 1 — Hosted (cards / net banking / wallets / hosted UPI)
Picks SabPaisa, clicks Confirm Order
Calls POST /api/v2/payments (hosted-create); order moved to Pending with merchantTxnId + paymentId in history
Redirected to SabPaisa's hosted checkout and pays
On return, re-enquires server-side → SUCCESS / FAILED / PENDING
Order moved to the mapped status → redirect to success/failure
Flow 2 — Native UPI (QR on your own page)
Clicks “Pay by UPI (scan QR)”
Calls POST /api/v2/payments/s2s with UPI_QR → SabPaisa returns a upi://pay?… string
Renders the QR locally (bundled qrcode.min.js — no external call) and polls the upi_status route
On a terminal state, moves the order to the mapped status and redirects
merchantTxnId (SP<digits>X…), never by amount.Refunds
Refunds are available directly in the admin. Open Sales → Orders, edit an order paid via SabPaisa, and use the SabPaisa tab on the order-info page — it shows the gateway transaction, the paid amount, and any existing refunds, and lets you issue a full or partial refund (amount defaults to the full paid amount).
modify) and writes a note to the order history without changing the order status. Refunds settle in 5–7 business days.Currency Handling
SabPaisa settles in INR. OpenCart stores the order total in the store's default currency, so the extension converts it to INR via OpenCart's own currency converter before sending (amount = INR × 100 = paise). This works for any store currency — no per-currency code.
- •Recommended: set the store's default currency to
INR— the total is sent as-is, with no FX drift. - •If the default is non-INR, keep an accurate INR currency + rate in Catalog → Currencies (OpenCart doesn't auto-refresh unless enabled). If no usable INR rate exists, the extension fails the payment cleanly and logs the reason rather than charging a wrong amount.
Troubleshooting
The extension writes failures to system/storage/logs/ with the SabPaisa error code, HTTP status, and traceId — always capture the traceId when escalating to support.
“We could not start the payment” on a localhost / plain-HTTP store
SabPaisa PG v2 rejects a non-HTTPS returnUrl with HTTP 400. This is expected, not a bug. Fix it by setting an HTTPS store URL in OpenCart's store settings, or by putting an HTTPS tunnel in front of your local store and configuring the store URL to that hostname.
Payment succeeded but the order is still pending
The order updates when the customer returns through the callback route. If they closed the browser first, use Admin Re-check (re-enquires SabPaisa and updates the order) or rely on the webhook (the right path for async UPI). Order-history comments hold the merchantTxnId and paymentId to look the transaction up.
INVALID_SIGNATURE on every transaction
The legacy hmac_api_key (64-char hex) was entered in the Secret Key field. Replace it with the sec_… value from your SabPaisa onboarding.
Native UPI button falls back to hosted (S2S_NOT_ENABLED)
Your merchant doesn't have S2S enabled, so native UPI silently falls back to the hosted flow — no action needed unless you want native UPI live, in which case contact SabPaisa support to enable S2S.
401 on the webhook receiver
The Webhook Secret is wrong, the signature was tampered with, or the timestamp is older than 300 seconds. Verify the webhook secret matches the one configured in your SabPaisa dashboard.
Re-checking a stuck order (admin URL)
1OpenCart 3.x:
2/admin/index.php?route=extension/payment/sabpaisa/recheck&user_token=<token>&order_id=<id>
3
4OpenCart 4.x:
5/admin/index.php?route=extension/sabpaisa/payment/sabpaisa.recheck&user_token=<token>&order_id=<id>Permission-gated (modify on the extension), idempotent (no history row if nothing changed), and never re-charges. For more common issues, see the Troubleshooting guide.
Need Help?
For installation or configuration help, contact SabPaisa support with:
- Your Merchant ID and OpenCart version (3.x / 4.x)
- The traceId from
system/storage/logs/ - The order id /
merchantTxnIdinvolved
Was this page helpful?