# WooCommerce plugin

Drop-in payment gateway for WordPress

# WooCommerce plugin

The plugin adds **Southbill** as a payment gateway in WooCommerce. It works on classic checkout and Cart/Checkout Blocks, handles both live and test modes, and receives webhooks to reconcile orders even if the buyer closes the tab.

Current version: **1.4.2** — download it from **Dashboard → Integrations → WooCommerce**.

## Requirements

- WordPress 6.0+, WooCommerce 6.0+
- PHP 7.4+
- Non-plain permalinks (needed for the WC REST API)

## Install

1. **Dashboard → Integrations → WooCommerce → Download plugin** — the ZIP is generated on the fly.
2. **WP Admin → Plugins → Add New → Upload Plugin** → pick `southbill-woocommerce-1.4.2.zip` → **Install** → **Activate**.
3. **WooCommerce → Settings → Payments** → enable **Southbill**.

## Configure

Open the Southbill gateway settings and fill in:

| Field | What to paste |
|---|---|
| **Live API key** | An `sk_live_...` key from Dashboard → Developers → API keys. |
| **Test API key** | An `sk_test_...` key. |
| **Mode** | `Live` in production, `Test` while integrating. |
| **Webhook signing secret** | The `whsec_...` shown when you create the webhook endpoint (next step). |

## Register the webhook

In **Dashboard → Developers → Webhooks → Add endpoint** set:

- **URL:** `https://your-store.com/wc-api/southbill`
- **Events:** `checkout.session.completed`, `payment.succeeded`, `payment.failed`, `charge.refunded`

Copy the signing secret into the plugin's **Webhook signing secret** field. Without it the plugin rejects every incoming call with `401 invalid signature` and orders stay `pending`.

## Order flow

1. Customer places order → WooCommerce calls `POST /v1/checkout/sessions` with the cart total, currency, and `metadata.wc_order_id`.
2. Customer is redirected to `checkout_url` (Southbill hosted checkout).
3. On success:
   - Southbill redirects the buyer to WooCommerce's return URL.
   - Southbill sends `payment.succeeded` to `/wc-api/southbill`.
   - Plugin verifies the signature (5-minute replay tolerance), matches the order by `metadata.wc_order_id`, and calls `payment_complete()`.
4. If the buyer closes the tab, the webhook still completes the order — the redirect is not the source of truth.

## Idempotency

The plugin stores the last 50 `event.id`s per order in post meta (`_southbill_events_seen`). Duplicate deliveries are skipped without side effects.

## Testing

Switch the plugin to **Test**, place a real order, pay with `4242 4242 4242 4242` (any future expiry, any CVC). The order should move to **Processing** within a few seconds of the redirect.

## Troubleshooting

| Symptom | Fix |
|---|---|
| Gateway not visible at checkout | Confirm the plugin is activated and toggled on in WC → Settings → Payments. |
| `401 invalid signature` in server log | Signing secret in plugin ≠ secret shown in dashboard. Regenerate the endpoint and re-paste. |
| Order stuck at `pending` after redirect | Webhook URL wrong or blocked by firewall. Test with `curl -X POST https://your-store.com/wc-api/southbill -d '{}'` — must return `401` (signature missing), not `404`. |
| `rest_no_route` in WP debug log | Permalinks are set to Plain. Switch to Post name in WP → Settings → Permalinks. |