← Integrations

Swapspay for OpenCart

OpenCart 4.0.2.x; PHP 8+ with cURL; single-store. Not an OpenCart 3 package.
## Installation
1. Upload swapspay.ocmod.zip through Extensions → Installer, then install the extension. Open Extensions → Payments, install Swapspay and edit its settings.
2. Save your live API key and webhook signing secret. The callback URL shown is normally https://YOUR-STORE/index.php?route=extension/swapspay/payment/swapspay.webhook.
3. Choose an unpaid waiting status, such as Pending, and a paid status from your store's processing/completed statuses. The settings page rejects a paid waiting status. Enable the gateway and save.
4. Check out with Cryptocurrency (Swapspay). The order history records the Payment ID; signed updates verify the payment through the API before changing the order status.
5. For backup reconciliation, copy cron.php outside the web root. Set SWAPSPAY_STORE_URL to the HTTPS store base URL and SWAPSPAY_WEBHOOK_SECRET to the signing secret in a private server environment file readable only by the cron user. Run php /private/path/cron.php every five minutes. No secret belongs in the cron URL. Your web server must forward the Authorization header to PHP.

OpenCart 3 and 4 have incompatible extension layouts. Do not install this ZIP into OpenCart 3. This first package targets the 4.0.2.x extension API. Confirm compatibility separately before using on OpenCart 4.1 or third-party checkout replacements. Recurring cart subscriptions are deliberately excluded.

Before enabling payments

Use HTTPS and a dedicated live API key created in Swapspay → API keys. The website attached to that key must be your store hostname. Create a webhook in Swapspay → Webhooks using the callback URL below, then copy its signing secret into the plugin. Send a connection-test event and verify delivery in Swapspay.

Every payment gets a separate Swapspay Payment ID. The order reference stays your order reference. The customer uses the existing hosted checkout, with a fresh deposit address and automatic detection; there is no TXID form. USDC/USDT use 1 token per USD, with other invoice currencies converted by Swapspay. Asset availability comes from the hosted checkout, so plugins do not hard-code a coin list.

Payment handling

Only an authenticated API response with live mode, matching Payment ID, reference, currency and amount, and status paid can complete the order. A webhook is a wake-up signal, not proof of payment. Repeated requests reuse the same payment; duplicate callbacks do not credit the order twice. Pending, confirming, underpaid and expired payments are not marked paid. Cancelled or changed orders require manual review. If the invoice changes after a payment is created, review it rather than reusing its checkout for a different amount. Do not rotate keys with pending requests until reconciled; each store should use its own key.

No automatic refunds, conversion, recurring debits or subscription mandates are provided. Recurring invoices can be paid individually where the platform generates a new invoice. Supported currencies are those available in Swapspay; invoices must resolve to positive amounts with at most two nonzero decimal places. There is no platform surcharge added by these plugins.

Release validation

Version 1.0.0. PHP syntax and payment-contract checks run against these packages. A real payment has not been completed on a WHMCS, PrestaShop or OpenCart store for this release. Before customer use, test your platform version and theme: create an invoice with cents, retry creation, complete a small payment, replay its webhook, then verify that wrong signatures, changed totals and unconfirmed payments cannot fulfil orders. Check mail, tax, shipping and stock behaviour in your store. Keep your store backup before installation.

Troubleshooting

If an order stays pending, check webhook delivery logs in Swapspay, then your store's payment log. Confirm that the API key and webhook belong to the same website. Retry failed webhooks from Swapspay. Quote-expired, underpaid, late and changed-order payments require merchant review; do not fulfil from a customer screenshot or checkout return. Backup polling checks the oldest unchecked pending rows first, up to 20 per run for seven days. After seven days, use webhook retries and manual review. Uninstalling preserves financial records. Disable the payment method before removing files and finish pending orders first.

Download OpenCart plugin