Guides
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 is inside.
Install
- 1
Get the zip
The plugin is on its way to WordPress.org. Until it is listed, write to us 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, 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:
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 | 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 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.