ガイド

WooCommerce

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

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

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

インストール

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

設定

項目（プラグインでの表示）	入力するもの
Secret key（シークレットキー）	Dashboard → Developers → API keys から。テストモードには `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`）	支払い済み：選んだステータス、在庫を減算、購入者へのメール。各送金とそのトランザクションを記したメモ。
検出、一部支払い、支払い済みだが確認中	メモ。支払い待ちのまま。
確認のため保留	保留中、理由付き。Perly Pay で判断します。
期限切れまたはキャンセル、支払いなし	キャンセル済み。
一部支払いのまま期限切れ	保留中：Perly Pay で返金するか承認します。
返金済み	全額なら返金済み、一部ならメモ。

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

返金

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

本番開始

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