# WooCommerce

> WooCommerce の決済方法：ビットコインと USDC/USDT があなたのウォレットに直接届き、署名付き Webhook が注文を支払い済みにします。

Perly Pay プラグインは、クラシックな購入手続きと Checkout ブロックに暗号資産を追加します。各注文は Perly Pay の請求書になり、購入者はストアの上か専用ページで支払い、署名付き Webhook が注文を支払い済みにします。WordPress 6.5+、WooCommerce 8.6+、PHP 8.1+。サーバーに何かを入れる必要はありません：[PHP SDK](https://pay.perly.io/docs/sdks.md) が同梱されています。

> **注:** 請求書は USD か EUR です。他の通貨のストアでは決済方法は表示されず、その設定画面に理由が表示されます。

## インストール

1. **zip を入手** — プラグインは WordPress.org に掲載予定です。それまでは `perly-pay-woocommerce.zip` を[お問い合わせ](https://pay.perly.io/ja/contact)からご依頼ください。
2. **インストール** — WordPress で：プラグイン → 新規プラグインを追加 → プラグインのアップロード、zip を選び、有効化します。WooCommerce が有効である必要があります。
3. **設定を開く** — WooCommerce → 設定 → 決済 → **Perly Pay**。

## 設定

| 項目（プラグインでの表示） | 入力するもの |
| --- | --- |
| Secret key（シークレットキー） | Dashboard → Developers → API keys から。[テストモード](https://pay.perly.io/docs/test-mode.md)には `sk_test_…`、本物のお金には `sk_live_…`。どちらのモードかは設定画面に表示されます。 |
| Webhook signing secret（Webhook の署名シークレット） | `whsec_…`。**Set up webhook** で自動入力されます。 |
| Payment page（支払いページ） | **Overlay** はストアの上に支払い画面を開きます（pay.js）。**Redirect** は購入者をそのページへ移動させます。スマートフォンでは常にページそのものが開きます。 |
| Status when paid（支払い後のステータス） | WooCommerce の判断に従う（処理中、ダウンロード商品は完了）、常に処理中、または常に完了。 |
| Title, Description（タイトル、説明） | 購入手続きで購入者に表示される内容。 |
| Debug log（デバッグログ） | イベントとエラーを WooCommerce → ステータス → ログ に記録。キー、シークレット、購入者の情報は決して記録しません。 |

1. **キーを貼る** — 続いて **Test connection** を押します：キーが使えるか、そのモード、このストアの Webhook が Perly Pay にあるかが表示されます。
2. **Webhook を設定** — **Set up webhook** を押します。ストアのアドレス（ボタンの上に表示、`…/wp-json/perly-pay/v1/webhook`）を Perly Pay に追加し、シークレットを保存します。または Developers → Webhooks で自分で追加し、シークレットを貼ります。
3. **Overlay を許可** — Dashboard → Settings で、ストアのアドレスを **Sites that may embed the checkout** に追加します。これがないと、Overlay は新しいタブで支払い画面を開くよう案内します。
4. **有効にする** — **Take crypto with Perly Pay**（Perly Pay で暗号資産を受け取る）にチェックを入れて保存します。

## テスト

`sk_test_…` キーで、自分のストアで注文し、Perly Pay を選びます。注文は**支払い待ち**になります。テスト用の通貨で、または API で請求書を支払います — その ID は注文メモにあります：

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

数秒で注文は**処理中**になり、ネットワーク、金額、トランザクションへのリンクを記したメモが付きます。請求書のページで通貨を選んだ後なら、`{"outcome":"short"}` と `{"outcome":"over"}` で他のケースも試せます。

## 注文が支払いに追従する仕組み

| Perly Pay では | 注文 |
| --- | --- |
| 支払い済み、送金者を確認済み（`invoice.fulfilled`） | 支払い済み：選んだステータス、在庫を減算、購入者へのメール。各送金とそのトランザクションを記したメモ。 |
| 検出、一部支払い、支払い済みだが確認中 | メモ。支払い待ちのまま。 |
| [確認](https://pay.perly.io/docs/screening.md)のため保留 | 保留中、理由付き。Perly Pay で判断します。 |
| 期限切れまたはキャンセル、支払いなし | キャンセル済み。 |
| 一部支払いのまま期限切れ | 保留中：Perly Pay で返金するか承認します。 |
| 返金済み | 全額なら返金済み、一部ならメモ。 |

各イベントは、それが作られた注文に一度だけ適用され、遅れて届いた「期限切れ」が支払いを取り消すことはありません。購入者が Webhook より先にサンクスページに戻った場合、プラグインは API に問い合わせてすぐに注文を更新します。

## 返金

いつもどおり注文ページから返金します：プラグインが Perly Pay で、支払われた通貨での[返金](https://pay.perly.io/docs/refunds.md)を開始します（一部返金なら一部を）。Perly Pay がメールで購入者にアドレスを尋ねて確認し、注文メモに何をどこへ送るかが表示されます。あなたが自分のウォレットから送金し、トランザクション ID を Perly Pay に貼ります — Perly Pay がお金を預かることはありません。

## 本番開始

- Perly Pay で本番モードをオンにし、ウォレットの公開鍵を接続します。
- `sk_live_…` キーを貼ります。本番のキーと Webhook はテストとは別です：もう一度 **Set up webhook** を押してください。
- 本番モードの **Sites that may embed the checkout** に、本番ストアの https アドレスを追加します。
- 少額の本番の注文を 1 件行い、返金してみます。