> ## 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

> WooCommerce（WordPress）にZAFA PAY決済を導入する方法

## 概要

WooCommerceの決済ゲートウェイプラグインとしてZAFA PAYを導入できます。ホスト型チェックアウトを使用するため、カード情報をサイト側で扱う必要はありません。

## ダウンロード

<Card title="ZAFA PAY Gateway for WooCommerce v1.0.0" icon="download" href="https://zafapay.com/downloads/woocommerce-zafapay-gateway.zip">
  プラグインをダウンロード（ZIP）
</Card>

## 要件

* WordPress 5.0以上
* WooCommerce 5.0以上
* PHP 7.4以上
* ZAFA PAYのマーチャントアカウント

## 導入フロー

<Steps>
  <Step title="プラグインのインストール">
    ダウンロードしたZIPファイルを WordPress管理画面の **プラグイン → 新規追加 → プラグインのアップロード** からインストールして有効化します
  </Step>

  <Step title="WooCommerce設定">
    WooCommerce → 設定 → 決済 → **ZAFA PAY** でAPIトークンとWebhookシークレットを設定します
  </Step>

  <Step title="ZAFA PAYダッシュボード設定">
    Webhook URLとリダイレクトURLを設定します
  </Step>

  <Step title="テスト決済">
    サンドボックスモードでテスト決済を行い、動作を確認します
  </Step>
</Steps>

## プラグイン設定

WooCommerce管理画面（**WooCommerce → 設定 → 決済 → ZAFA PAY**）で以下を設定します。

| 項目                | 説明                                     |
| ----------------- | -------------------------------------- |
| **有効/無効**         | ZAFA PAYゲートウェイの有効化                     |
| **タイトル**          | チェックアウト画面に表示される決済方法名                   |
| **説明**            | チェックアウト画面に表示される説明文                     |
| **サンドボックスモード**    | テスト環境（sandbox）と本番環境の切り替え               |
| **APIトークン**       | ZAFA PAYダッシュボードのMerchant Settingsから取得  |
| **Webhookシークレット** | ZAFA PAYダッシュボードでWebhook登録時に発行されるシークレット |
| **Flow ID**       | 特定の決済フローを使用する場合に入力（任意）                 |

<Warning>
  サンドボックスと本番ではAPIトークンが異なります。環境を切り替える際はトークンも変更してください。
</Warning>

## ZAFA PAYダッシュボード設定

### Webhook URL

ZAFA PAYダッシュボードの**Webhooks**タブで以下のURLを登録してください。

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

受信するイベント:

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

### リダイレクトURL

ZAFA PAYダッシュボードの**リダイレクトURL**設定に以下を登録してください。

| 項目           | URL                                               |
| ------------ | ------------------------------------------------- |
| 成功時リダイレクトURL | `https://your-domain.com/wc-api/zafapay_callback` |
| 失敗時リダイレクトURL | `https://your-domain.com/wc-api/zafapay_callback` |
| キャンセルURL     | `https://your-domain.com/checkout/`               |

<Info>
  成功と失敗は同じURLです。ZAFA PAYがリダイレクト時に付与する `status` パラメータでプラグインが自動判別します。
</Info>

## 決済フロー

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

    Customer->>WC: チェックアウトで注文
    WC->>ZP: POST /v1/payments（決済作成）
    ZP-->>WC: payment_url を返却
    WC->>Customer: payment_url にリダイレクト
    Customer->>ZP: カード情報を入力・決済
    ZP->>WC: Webhook（payment.succeeded）
    ZP->>Customer: 成功URLにリダイレクト
    Customer->>WC: コールバック処理 → 注文完了ページ
```

## 返金

WooCommerce管理画面から返金を実行できます。

1. **WooCommerce → 注文** から対象の注文を開く
2. **「払戻額」** ボタンをクリック
3. 商品行の金額欄に返金額を入力
4. **「ZAFA PAY によって返金します」** ボタンをクリック

部分返金と全額返金の両方に対応しています。

## 対応する注文ステータス

| イベント                   | WooCommerceステータス |
| ---------------------- | ---------------- |
| 決済成功                   | 処理中              |
| 決済失敗                   | 失敗               |
| キャンセル                  | キャンセル            |
| 返金                     | 返金済み（注文メモに記録）    |
| チャージバック                | 保留中              |
| オーソリ済み（manual capture） | 保留中              |

## API環境

| 環境      | API URL                           |
| ------- | --------------------------------- |
| サンドボックス | `https://api.sandbox.zafapay.com` |
| 本番      | `https://api.zafapay.com`         |