# WooCommerce

Official WooCommerce payment gateway plugin for ZevPay Checkout. Supports inline modal and standard (redirect) checkout flows.

## Installation

1. Download the plugin from the [WordPress Plugin Directory](https://wordpress.org/plugins/zevpay-checkout-for-woocommerce/) or install via **Plugins > Add New** in WordPress
2. Activate the plugin
3. Go to **WooCommerce > Settings > Payments > ZevPay Checkout**
4. Enter your API keys

Requires WordPress 5.8+, WooCommerce 7.0+, and PHP 7.4+.

## Configuration

### API keys

Enter your public and secret keys from the [ZevPay Dashboard](https://dashboard.zevpaycheckout.com):

| Field | Description |
|-------|-------------|
| Public API Key | `pk_live_*` or `pk_test_*` |
| Secret API Key | `sk_live_*` or `sk_test_*` |
| Webhook Secret | Signing secret from your Dashboard |

### Checkout mode

Choose between two checkout experiences:

| Mode | Description |
|------|-------------|
| **Inline Modal** | Opens the ZevPay payment form in a modal overlay on your site. The customer never leaves your checkout page. |
| **Standard (Redirect)** | Redirects the customer to the ZevPay hosted checkout page to complete payment. |

### Payment methods

Select which payment methods to offer:

- **Bank Transfer** — Customer transfers to a virtual account
- **PayID** — Customer pays via ZevPay ID
- **Card** — Card payment

Leave the selection empty to use whatever methods you configured in your ZevPay Dashboard.

### Pass order details (Standard mode)

When enabled, the plugin forwards order metadata to the hosted checkout page:

- Customer name and email
- Order reference
- Order ID and key in metadata

## How it works

### Inline flow

```
Customer → Checkout → Order Pay Page → "Pay with ZevPay" button
         → Modal opens → Customer pays → AJAX verify → Order complete
         → Webhook confirms asynchronously
```

1. Customer selects ZevPay Checkout as their payment method
2. After placing the order, they are redirected to the order-pay page
3. Clicking "Pay with ZevPay" loads the inline SDK and opens the payment modal
4. Customer completes payment in the modal
5. The frontend sends an AJAX request to verify the payment via the ZevPay API
6. If verified, the order is marked as paid and the customer sees the thank-you page
7. A webhook event confirms the payment asynchronously

### Standard flow

```
Customer → Checkout → Server initializes session → Redirect to ZevPay
         → Customer pays on hosted page → Redirect back → Verify → Order complete
         → Webhook confirms asynchronously
```

1. Customer selects ZevPay Checkout as their payment method
2. The plugin initializes a checkout session via the ZevPay API (using the [PHP SDK](/sdks/php))
3. Customer is redirected to the ZevPay hosted checkout page
4. Customer completes payment
5. Redirected back to WooCommerce where the session is verified
6. Order is marked as paid
7. A webhook event confirms the payment asynchronously

## Webhook setup

1. In the plugin settings page, copy the **webhook URL** shown in the info box
2. Go to your [ZevPay Dashboard](https://dashboard.zevpaycheckout.com) webhook settings
3. Paste the URL and save
4. Copy the **webhook secret** and paste it in the plugin's "Webhook Secret" field

The plugin uses the [PHP SDK's `Webhook::constructEvent()`](/sdks/php#webhook-verification) to verify the `x-zevpay-signature` header.

::: warning Always configure webhooks
Webhooks provide reliable server-to-server payment confirmation. The inline callback and standard redirect are customer-initiated and may fail if the customer closes their browser. Webhooks ensure your orders are always updated.
:::

## Settings reference

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| Enable/Disable | Checkbox | Off | Enable the gateway |
| Title | Text | "ZevPay Checkout" | Payment method title at checkout |
| Description | Textarea | "Pay securely..." | Description below the title |
| Public API Key | Text | — | Your `pk_live_*` or `pk_test_*` key |
| Secret API Key | Password | — | Your `sk_live_*` or `sk_test_*` key |
| Webhook Secret | Password | — | Webhook signing secret |
| Checkout Mode | Select | Inline | `inline` or `standard` |
| Payment Methods | Multiselect | — | Bank Transfer, PayID, Card (empty = Dashboard settings) |
| Pass Order Details | Checkbox | On | Send order info in Standard mode |
| Logging | Checkbox | Off | Debug logs in WooCommerce > Status > Logs |

## Compatibility

| Feature | Status |
|---------|--------|
| WooCommerce Blocks | Supported |
| HPOS (High-Performance Order Storage) | Supported |
| Classic checkout | Supported |
| WordPress Multisite | Supported |

## Troubleshooting

### Gateway not appearing at checkout

- Verify the gateway is enabled in **WooCommerce > Settings > Payments**
- Confirm your store currency is set to **NGN** (Nigerian Naira)
- Check that both public and secret API keys are entered

### Payment not confirming

- Verify your webhook URL is correctly configured in the ZevPay Dashboard
- Check the webhook secret matches
- Enable logging and check **WooCommerce > Status > Logs** for errors

### Debug logging

Enable "Logging" in the plugin settings. Logs appear in **WooCommerce > Status > Logs** with source `zevpay_checkout`.

## Resources

- [API Reference](/api/overview) — Full endpoint documentation
- [PHP SDK](/sdks/php) — Server-side SDK used by this plugin
- [Webhook Events](/webhooks/events) — All event types
- [WordPress Plugin Directory](https://wordpress.org/plugins/zevpay-checkout-for-woocommerce/) — Plugin page