Integrate

Take crypto on your site

Pick a way. Copy, paste, done.

Three ways

1
Make a product
New product
Name
House Blend · 1 kg
Price
24.00USD
House Blend · 1 kg$24.00Active
2
Copy its link
Link
```
https://pay.perly.io/l/your-link
```
pay.perly.io/l/your-link
Or print the QR.
Link copied

Paste it anywhere

Bio, message, email, button, QR on a counter.

Where the link goes

Instagram, TikTok	Edit profile → Links → paste
Telegram, WhatsApp	Paste in a message or a channel post
Email	Paste in the text, or under a word
Wix	Button → Link → Web address → paste
Tilda	Button block → Content → Button link → paste
Webflow	Button → Settings → Link → URL → paste
WordPress	Buttons block → Link → paste
Shopify	Customize theme → Button → Link → paste
Notion	Select text → Link → paste

On a site builder: add a button, set its link.

northwind.coffee

Roasted on Fridays.

pay.perly.io/l/your-link

Bio

Chat

How do I pay?pay.perly.io/l/your-link

Message

Your order

Pay here →

Buy now

Link

pay.perly.io/l/your-link

✓ Done

Site builder

4
The buyer pays
House Blend · 1 kg
$24.00
BTC
USDC
USDT
USDC · Base
24.000000 USDC
Paid

1
Allow your site
Settings → Checkout → Sites that may embed the checkout.
Checkout
Sites that may embed the checkout
https://yourshop.com
Saved

Copy two lines

data-paid-url is where buyers land after paying. Optional.

HTML

<script src="https://pay.perly.io/pay/v1.5bdf2776ee74.js" integrity="sha384-W98ndu50hymNVBtxKpwAcr3BxXUEFVzpxXZGF4AzqToIFMBPrQFVd4H60xXBzVJZ" crossorigin="anonymous" defer></script>
<button data-perly-pay="your-link" data-paid-url="/thanks">Pay with crypto</button>

3
Paste before </body>
Any page. Just above </body>.
index.html Pasted
1<!doctype html>
2<html>
3<body>
4 <h1>Northwind Coffee</h1>
5 <p>House Blend · 1 kg — $24</p>
6 <script src="https://pay.perly.io/pay/v1.5bdf2776ee74.js" integrity="sha384-W98ndu50hymNVBtxKpwAcr3BxXUEFVzpxXZGF4AzqToIFMBPrQFVd4H60xXBzVJZ" crossorigin="anonymous" defer></script>
7 <button data-perly-pay="your-link" data-paid-url="/thanks">Pay with crypto</button>
8</body>
9</html>
← Paste here
4
Click it: the checkout opens over your site
Your page also hears it:
perlypay:paid
```
<script>
  addEventListener("perlypay:paid", (e) => {
    console.log("Paid", e.detail.invoice); // inv_…
  });
</script>
```
Northwind Coffee
House Blend · 1 kg
$24.00
Pay with crypto
Thank you!
Your coffee ships tomorrow.
pay.perly.io
Northwind Coffee
$24.00
BTC
USDC
Paid
perlypay:paid { invoice: "inv_3f2a…" }

1
Get a test key
The secret key stays on your server. Never in a page.
API keys
Local dev
sk_test_…
Copy it now. It is shown once.
sk_test_••••••••••••••••
2
Install the SDK
```
npm i perly-pay
```
~/shop $ npm i perly-pay
added 1 package in 1s
0 dependencies · TypeScript types included
ready

Make an invoice, send the buyer to it

import { PerlyPay } from "perly-pay";

const pay = new PerlyPay(process.env.PERLY_PAY_KEY); // sk_test_…

app.post("/buy", async (req, res) => {
  const invoice = await pay.invoices.create({
    line_items: [{ price: "price_…" }],
    return_url: "https://yourshop.com/thanks",
    metadata: { order: "1042" },
  });
  res.redirect(303, invoice.url); // https://pay.perly.io/i/<uuid>
});

Hear about it: a webhook

Verify the raw body. Ship on invoice.fulfilled — it comes once, after screening.

app.post("/webhooks/perly", express.raw({ type: "application/json" }), (req, res) => {
  const event = pay.webhooks.verify(
    req.body,                         // the raw bytes, not parsed JSON
    req.header("Perly-Signature"),
    process.env.PERLY_PAY_WEBHOOK_SECRET,  // whsec_…
  ); // throws if forged, or older than 5 minutes

  if (event.type === "invoice.fulfilled") {
    ship(event.data.object.metadata.order); // once, after screening
  }
  res.sendStatus(204);
});

Webhooks

Endpoint URL

yourshop.com/webhooks/perly

https://yourshop.com/webhooks/perlyOn

whsec_•••• · shown once

invoice.paid200delivered

invoice.fulfilled200delivered

5
What happens, in order
invoice.paid comes first; invoice.fulfilled when it's safe to ship.
Buyer
Your site
Perly Pay
Chain
Your server
Buy
POST /invoices
invoice.url
Redirect to /i/…
Pays to your address
Seen, confirmed
invoice.paid · invoice.fulfilled
Receipt
Ship

Test it, then go live

1
Test mode on
Northwind CoffeeTest
Test networks. Nothing real moves.
2
Simulate payment
USDC · Base SepoliaPaid
24.000000
Simulate payment
3
See the webhook and the receipt
Webhooks
invoice.paid200delivered
invoice.fulfilled200delivered
receipt.created200delivered
Receipt
TEST-NW-2026-000124
House Blend · 1 kg$24.00
PDF
4
Go live: verify your wallet
Compare the first address on your wallet's own screen.
Wallets · live · first address
bc1q9h7…x7f2
Verify address
bc1q9h7…x7f2
Live

Copy a link. Paste it anywhere.

Start free Read the docs

Three ways

Make a product

Copy its link

Paste it anywhere

Where the link goes

The buyer pays

Allow your site

Copy two lines

Paste before </body>

Click it: the checkout opens over your site

Get a test key

Install the SDK

Make an invoice, send the buyer to it

Hear about it: a webhook

What happens, in order

Test it, then go live

Test mode on

Simulate payment

See the webhook and the receipt

Go live: verify your wallet

Copy a link. Paste it anywhere.