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

# WooCommerce

> How to integrate ZAFA PAY payments with WooCommerce (WordPress)

## Overview

ZAFA PAY can be integrated as a WooCommerce payment gateway plugin. It uses hosted checkout, so your site never handles card information directly.

## Download

<Card title="ZAFA PAY Gateway for WooCommerce v1.0.0" icon="download" href="https://zafapay.com/downloads/woocommerce-zafapay-gateway.zip">
  Download plugin (ZIP)
</Card>

## Requirements

* WordPress 5.0+
* WooCommerce 5.0+
* PHP 7.4+
* ZAFA PAY merchant account

## Setup Flow

<Steps>
  <Step title="Install Plugin">
    Upload the downloaded ZIP file via **Plugins → Add New → Upload Plugin** in the WordPress admin and activate it
  </Step>

  <Step title="WooCommerce Settings">
    Go to WooCommerce → Settings → Payments → **ZAFA PAY** and configure your API token and Webhook secret
  </Step>

  <Step title="ZAFA PAY Dashboard Settings">
    Configure the Webhook URL and redirect URLs
  </Step>

  <Step title="Test Payment">
    Run a test payment in sandbox mode to verify everything works
  </Step>
</Steps>

## Plugin Settings

Configure the following in the WooCommerce admin (**WooCommerce → Settings → Payments → ZAFA PAY**):

| Setting            | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| **Enable/Disable** | Enable the ZAFA PAY gateway                                     |
| **Title**          | Payment method name displayed at checkout                       |
| **Description**    | Description displayed at checkout                               |
| **Sandbox Mode**   | Toggle between sandbox and production environments              |
| **API Token**      | Obtained from ZAFA PAY dashboard under Merchant Settings        |
| **Webhook Secret** | Issued when registering a Webhook URL in the ZAFA PAY dashboard |
| **Flow ID**        | Specify a payment flow to use (optional)                        |

<Warning>
  Sandbox and production use different API tokens. Make sure to update the token when switching environments.
</Warning>

## ZAFA PAY Dashboard Settings

### Webhook URL

Register the following URL in the **Webhooks** tab of the ZAFA PAY dashboard:

```
https://your-domain.com/wc-api/zafapay_webhook
```

Events to subscribe:

* `payment.succeeded`
* `payment.failed`
* `payment.canceled`
* `payment.refunded`
* `payment.chargeback`

### Redirect URLs

Configure the following in the **Redirect URL** settings of the ZAFA PAY dashboard:

| Setting              | URL                                               |
| -------------------- | ------------------------------------------------- |
| Success Redirect URL | `https://your-domain.com/wc-api/zafapay_callback` |
| Failure Redirect URL | `https://your-domain.com/wc-api/zafapay_callback` |
| Cancel URL           | `https://your-domain.com/checkout/`               |

<Info>
  Success and failure use the same URL. The plugin automatically determines the result based on the `status` parameter appended by ZAFA PAY.
</Info>

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant WC as WooCommerce
    participant ZP as ZAFA PAY

    Customer->>WC: Place order at checkout
    WC->>ZP: POST /v1/payments (create payment)
    ZP-->>WC: Return payment_url
    WC->>Customer: Redirect to payment_url
    Customer->>ZP: Enter card details & pay
    ZP->>WC: Webhook (payment.succeeded)
    ZP->>Customer: Redirect to success URL
    Customer->>WC: Callback handler → order confirmation page
```

## Refunds

Refunds can be processed from the WooCommerce admin:

1. Go to **WooCommerce → Orders** and open the target order
2. Click the **"Refund"** button
3. Enter the refund amount in the product line item fields
4. Click **"Refund via ZAFA PAY"**

Both partial and full refunds are supported.

## Order Status Mapping

| Event                       | WooCommerce Status  |
| --------------------------- | ------------------- |
| Payment succeeded           | Processing          |
| Payment failed              | Failed              |
| Canceled                    | Cancelled           |
| Refunded                    | Note added to order |
| Chargeback                  | On Hold             |
| Authorized (manual capture) | On Hold             |

## API Environments

| Environment | API URL                           |
| ----------- | --------------------------------- |
| Sandbox     | `https://api.sandbox.zafapay.com` |
| Production  | `https://api.zafapay.com`         |