Perly Pay

List invoices. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create an invoice. Lines are prices (`{ price, quantity }`) or your own (`{ description, amount, quantity }`), in one currency. For a single amount, `amount` + `description` is short for one line. `customer` is an id or `{ email }`. A price line may carry its own `description` ("Seat #12"), and `discount` takes an amount off this invoice alone. The buyer pays at `url`, choosing bitcoin or a stablecoin there. Live mode: a new invoice is refused with 403 `bill_overdue` while a Perly Pay bill is unpaid past its 14 days, until it is paid in the dashboard's Billing; invoices already made are still paid. Test keys only: refused with a live key.

Retrieve an invoice.

Cancel an invoice. Only while nothing has arrived. Money that arrives later is still seen (the address stays watched) and lands in review. Test keys only: refused with a live key. Cannot be undone — Cancels the invoice: its buyer can no longer pay it. Ask the person first, then call with `confirm: true`.

Simulate a payment (test mode only). Test keys only. `full` pays the amount due: the invoice turns paid and is fulfilled — entitlements, license keys, a receipt, and the events your webhooks get. `short` sends half (underpaid), `over` a tenth more (overpaid); those two need the buyer's chain and asset chosen first. For `full`, an invoice with no chain yet gets one: `chain` and `asset` if given, else the first stablecoin offered (refund terms count as accepted). Pass the invoice's `id`, or a `payment_link` id: then a test invoice is made for the link's price (as a buyer opening the link would) and paid. Test keys only: refused with a live key.

Create a checkout session. A cart of 1–20 prices in one currency. Send the buyer to `url`, or open it in an overlay with pay.js (`data-session="cs_…"`). The buyer comes back to `return_url` after paying, `cancel_url` if they leave. Live mode: a new session is refused with 403 `bill_overdue` while a Perly Pay bill is unpaid past its 14 days. Test keys only: refused with a live key.

Retrieve a checkout session.

List products. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a product. Test keys only: refused with a live key.

Update a product. Set `active: false` to stop selling it; products are never deleted (invoices point at them). Test keys only: refused with a live key.

List prices. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a price. Every model: one_time, pay_what_you_want (with a minimum), fixed_term (N days of access), subscription (interval, trial, grace, prepay), lifetime (optional cap and cohort tiers), credit_pack. Amounts are immutable; make a new price to change one. Body is one of: model = one_time: needs product, model, unit_amount; model = pay_what_you_want: needs product, model, custom_amount; model = fixed_term: needs product, model, unit_amount, term_days; model = subscription: needs product, model, unit_amount, recurring; model = lifetime: needs product, model; model = credit_pack: needs product, model, unit_amount, credits. Test keys only: refused with a live key.

Update a price. Nickname, active, refund terms (`refunds` replaces them whole; what you leave out takes its default) and metadata. Amounts and the model never change. Test keys only: refused with a live key.

List customers. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a customer. Test keys only: refused with a live key.

Retrieve a customer.

List subscriptions. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a subscription. Renewed by invoice: the customer pays each period themselves. Without a trial the first invoice opens now (`latest_invoice`); the subscription turns active when it is paid. Test keys only: refused with a live key.

Retrieve a subscription.

List payment links. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a payment link. A page at /l/<slug> that sells one price. Share it anywhere, or open it with pay.js. Test keys only: refused with a live key.

Update a payment link. Test keys only: refused with a live key.

Check access. One call: may this customer use this product now? Name the customer by `customer`, `customer_email` or `customer_external_id`, and the product by `product` (or `price`).

List entitlements. Newest first; pass `next_cursor` back as `cursor` for the next page.

Spend credits. Spends credits from one credit pack, atomically. Refused when fewer are left. `action` labels the spend for your reports; with an `Idempotency-Key` a retry never spends twice. To spend from a customer's packs together, use POST /credits/consume. Test keys only: refused with a live key.

List credit spends. Newest first; pass `next_cursor` back as `cursor` for the next page.

List payments. Transfers seen on chain into addresses we handed out, newest first. Newest first; pass `next_cursor` back as `cursor` for the next page.

Retrieve a payment.

List refunds. Newest first; pass `next_cursor` back as `cursor` for the next page.

Open a refund. Starts a refund in the asset that was paid. We email the buyer a link to give an address; the link is never returned, since whoever holds it decides where the money goes. With no email on the invoice, the owner makes one in the dashboard. When the address is checked, the refund is `ready_to_send` with `amount_to_send`. Refused with `sanctioned_sender` when money on the invoice came from an address on a sanctions list, or one the coin's issuer froze: sending it back may itself be prohibited, so nothing refunds it — leave it and talk to a lawyer. Test keys only: refused with a live key. Cannot be undone — Opens a refund to the buyer. Ask the person first, then call with `confirm: true`.

List receipts. One for every fulfilled payment and every confirmed refund, newest first. Newest first; pass `next_cursor` back as `cursor` for the next page.

Retrieve a receipt.

List events. What happened in the last 30 days, newest first. `type` filters (`invoice.paid`, or `invoice.*`). Newest first; pass `next_cursor` back as `cursor` for the next page.

List webhook endpoints. Newest first; pass `next_cursor` back as `cursor` for the next page.

Create a webhook endpoint. The response carries `secret` — the only time you see it. Keep it to verify `Perly-Signature`. Test keys only: refused with a live key.

Delete a webhook endpoint. Test keys only: refused with a live key. Cannot be undone — Deletes the webhook endpoint: its events stop. Ask the person first, then call with `confirm: true`.

Checks a Perly Pay webhook on this machine: the HMAC-SHA256 in its Perly-Signature header against the raw body and the endpoint's signing secret, and that it is under five minutes old. Nothing is sent anywhere. Use it to debug a webhook handler that rejects real events. Pass the body exactly as received (the raw text, before JSON parsing). `secret` defaults to PERLY_PAY_WEBHOOK_SECRET.

The Perly Pay dashboard pages for steps no API key can take: pay a Perly Pay bill, connect a wallet (public key only), go live, set up two-factor sign-in, manage API keys and live webhooks, send live refunds, and the go-live checklist. Give the person the link and say what to do there; do not try these through other tools.