> ## Documentation Index
> Fetch the complete documentation index at: https://developer.quickei.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce

> Accept Quickei payments on your WordPress store

Add Quickei as a payment method in your WooCommerce store. Customers pay by scanning a QR code or via the hosted payment page — orders update automatically.

## Requirements

| Requirement | Minimum Version  |
| ----------- | ---------------- |
| WordPress   | 6.0+             |
| WooCommerce | 8.0+             |
| PHP         | 8.1+             |
| SSL         | Required (HTTPS) |

<Note>
  You need a Quickei merchant account with API keys. [Register here](https://quickei.io/merchant-register) if you don't have one.
</Note>

## Installation

<Steps>
  <Step title="Download the plugin">
    Download the Quickei WooCommerce plugin from your [Merchant Dashboard](https://quickei.io/merchant/integrations) or from the integration page.
  </Step>

  <Step title="Install in WordPress">
    Go to **Plugins > Add New > Upload Plugin** in your WordPress admin. Upload the `quickei-gateway.zip` file and activate it.
  </Step>

  <Step title="Configure API keys">
    Navigate to **WooCommerce > Settings > Payments > Quickei** and enter your credentials:

    * **Client ID** — Your merchant API client ID
    * **Client Secret** — Your merchant API secret
    * **Environment** — Sandbox for testing, Production for live payments
  </Step>

  <Step title="Test a payment">
    Place a test order using the Sandbox environment to verify everything works before going live.
  </Step>
</Steps>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant WooCommerce
    participant Quickei API
    participant Quickei App

    Customer->>WooCommerce: Checkout with Quickei
    WooCommerce->>Quickei API: POST /orders (amount, currency, callback_url)
    Quickei API-->>WooCommerce: order_id, qr_data, payment_url
    WooCommerce-->>Customer: Display QR code / payment page
    Customer->>Quickei App: Scan QR or open payment page
    Quickei App->>Quickei API: Complete payment
    Quickei API->>WooCommerce: Webhook (pos.order.paid)
    WooCommerce->>WooCommerce: Update order → Processing
```

## Checkout Experience

When a customer selects Quickei at checkout:

1. A **QR code** is displayed on the order confirmation page
2. The customer scans it with the **Quickei app** or clicks to open the **payment page**
3. Payment is confirmed in real-time — the page updates automatically
4. The WooCommerce order moves from **Pending** to **Processing**

## Webhook Configuration

The plugin automatically registers a webhook endpoint:

```
https://your-store.com/?wc-api=quickei_webhook
```

All webhook payloads are verified using **HMAC-SHA256** signatures with your `client_secret`.

### Event Mapping

| Quickei Event         | WooCommerce Status | Description                  |
| --------------------- | ------------------ | ---------------------------- |
| `pos.order.paid`      | Processing         | Payment confirmed            |
| `pos.order.expired`   | Failed             | Order expired before payment |
| `pos.order.cancelled` | Cancelled          | Order cancelled by merchant  |
| `pos.order.refunded`  | Refunded           | Payment refunded to customer |

## Plugin Settings

| Setting            | Description                           | Default                     |
| ------------------ | ------------------------------------- | --------------------------- |
| **Enable/Disable** | Toggle Quickei payment method         | Enabled                     |
| **Title**          | Payment method name shown at checkout | "Quickei"                   |
| **Description**    | Description shown at checkout         | "Pay securely with Quickei" |
| **Client ID**      | Your merchant API client ID           | —                           |
| **Client Secret**  | Your merchant API secret              | —                           |
| **Environment**    | Sandbox or Production                 | Sandbox                     |

<Warning>
  Always test in **Sandbox** mode first. Switch to **Production** only after verifying that orders, webhooks, and refunds work correctly.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="QR code not displaying at checkout">
    Ensure your API keys are correct and the plugin is enabled. Check your WordPress error log at `wp-content/debug.log` for API response errors.
  </Accordion>

  <Accordion title="Webhook not updating order status">
    Verify the webhook URL `https://your-store.com/?wc-api=quickei_webhook` is publicly accessible. Check that your server allows incoming POST requests from Quickei IPs.
  </Accordion>

  <Accordion title="SSL/HTTPS errors">
    Quickei requires HTTPS for all API communications. Ensure your WordPress site has a valid SSL certificate and `WP_HOME` / `WP_SITEURL` use `https://`.
  </Accordion>
</AccordionGroup>