# WooCommerce

> A payment method for WooCommerce: bitcoin and USDC/USDT straight to your wallet, orders marked paid by a signed webhook.

The Perly Pay plugin adds crypto to the classic checkout and the Checkout block. Each order becomes an invoice in Perly Pay; the buyer pays it over your store or on its own page; a signed webhook marks the order paid. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. Nothing to install on the server: the [PHP SDK](https://pay.perly.io/docs/sdks.md) is inside.

> **Note:** Invoices are in USD or EUR. In a store with another currency the payment method stays hidden, and its settings say why.

## Install

1. **Get the zip** — The plugin is on its way to WordPress.org. Until it is listed, [write to us](https://pay.perly.io/contact) for `perly-pay-woocommerce.zip`.
2. **Install** — In WordPress: Plugins → Add New → Upload Plugin, choose the zip, activate. WooCommerce must be active.
3. **Open the settings** — WooCommerce → Settings → Payments → **Perly Pay**.

## Settings

| Setting | What to put |
| --- | --- |
| Secret key | From Dashboard → Developers → API keys. `sk_test_…` for [test mode](https://pay.perly.io/docs/test-mode.md), `sk_live_…` for real money. The settings say which mode you are in. |
| Webhook signing secret | `whsec_…`. **Set up webhook** fills it in for you. |
| Payment page | **Overlay** opens the checkout over your store (pay.js). **Redirect** sends the buyer to it. Phones always get the page itself. |
| Status when paid | WooCommerce's own (Processing; Completed for downloads), always Processing, or always Completed. |
| Title, Description | What buyers see at checkout. |
| Debug log | Events and errors in WooCommerce → Status → Logs. Never keys, secrets or buyers' details. |

1. **Paste the key** — Then press **Test connection**: it says whether the key works, its mode, and whether this store's webhook is in Perly Pay.
2. **Set up the webhook** — Press **Set up webhook**. It adds the store's address (shown above the buttons, `…/wp-json/perly-pay/v1/webhook`) in Perly Pay and saves its secret. Or add it yourself in Developers → Webhooks and paste the secret.
3. **Allow the overlay** — In Dashboard → Settings, add the store's address to **Sites that may embed the checkout**. Without it the overlay offers to open the checkout in a new tab.
4. **Enable** — Tick **Take crypto with Perly Pay** and save.

## Test

With a `sk_test_…` key, place an order in your store and choose Perly Pay. The order waits as **Pending payment**. Pay the invoice with test coins, or from the API — its id is in the order's notes:

```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 '{}'
```

Within seconds the order is **Processing**, with a note naming the network, the amount and a link to the transaction. `{"outcome":"short"}` and `{"outcome":"over"}` try the other cases once a coin is chosen on the invoice page.

## How orders follow payments

| In Perly Pay | The order |
| --- | --- |
| Paid and the sender checked (`invoice.fulfilled`) | Paid: your chosen status, stock reduced, the buyer's email. A note with each transfer and its transaction. |
| Seen, part paid, paid but still screening | A note. Still pending. |
| Held for [review](https://pay.perly.io/docs/screening.md) | On hold, with the reason. Decide in Perly Pay. |
| Expired or canceled, nothing paid | Cancelled. |
| Expired with part paid | On hold: refund it or accept it in Perly Pay. |
| Refunded | Refunded in full, or a note for part. |

Each event is applied once, to the order it was made for, and a late "expired" never undoes a payment. When the buyer comes back to the thank-you page before the webhook, the plugin asks the API and updates the order then.

## Refunds

Refund from the order screen as usual: the plugin opens a [refund](https://pay.perly.io/docs/refunds.md) in Perly Pay, in the coin that was paid (part of it for a partial refund). Perly Pay emails the buyer for an address and checks it; the order's notes then say what to send where. You send from your wallet and paste the transaction id in Perly Pay — Perly Pay never holds the money.

## Go live

- Turn on live mode in Perly Pay and connect your wallet's public keys.
- Paste a `sk_live_…` key. Live keys and webhooks are separate from test ones: press **Set up webhook** again.
- Add your live store's https address to **Sites that may embed the checkout** in live mode.
- Place one small real order and refund it.