Guides
n8n
Crypto payments in any n8n workflow: a trigger for paid invoices, refunds and subscriptions, and a node that makes invoices and payment links.
The Perly Pay nodes bring your payments to n8n. A paid invoice can fill a sheet, email a download link or grant access; a form or a CRM step can create an invoice and send its payment page. Two nodes: Perly Pay, which does things, and Perly Pay Trigger, which starts a workflow.
Install
- 1
Install the nodes
Follow n8n's guide to installing community nodes with the package name
n8n-nodes-perly-pay. It is on npm, with its source on GitHub, and has no dependencies of its own. - 2
Get a key
In Perly Pay, Dashboard → Developers → API keys.
sk_test_…for test mode,sk_live_…for real money. Choose Full access, or Restricted with Webhook endpoints ticked: the trigger adds its own webhook. - 3
Add the credential
In n8n, add a Perly Pay API credential and paste the key. n8n tests it by listing your webhook endpoints.
Perly Pay node
| Resource | Operation | What it does |
|---|---|---|
| Invoice | Create | An invoice for an amount in USD or EUR, with its payment page (url) where the buyer picks a coin and network. Optional: the buyer's email, a return URL, how long the buyer has to choose, your own metadata. |
| Invoice | Get | An invoice by its ID: its status, what arrived and on which network. |
| Invoice | Get Many | Invoices, newest first, by status or customer. |
| Customer | Search | Customers by email, or all of them, newest first. |
| Payment Link | Create | A shareable payment page for one of your prices, or for a new one-time price from a name and an amount. |
Simplify, on by default, gives an invoice or a link as ten flat fields. Amounts come as integers (cents; coins in their smallest unit), each with a decimal string beside it: total is 4900 and total_decimal is "49.00".
Perly Pay Trigger
Choose the events that start the workflow. Activating the workflow adds a webhook in your Perly Pay account for those events, at the workflow's production URL; deactivating it deletes the webhook.
| Event | When |
|---|---|
Invoice Paid (invoice.fulfilled) | Paid in full, confirmed on its network and screened: the moment to deliver |
Payment Underpaid (invoice.underpaid) | Less than the invoice arrived. The buyer can send the rest. |
Refund Opened (refund.requested) | A refund was opened. Perly Pay asks the buyer for an address. |
Refund Confirmed (refund.confirmed) | The refund you sent from your wallet is confirmed on chain |
Subscription Started (subscription.created) | A subscription started |
Subscription Renewed (subscription.renewed) | A subscriber paid for the next period |
Subscription Ended (subscription.ended) | A subscription ended: the moment to take access away |
New Customer (customer.created) | A new buyer was added |
Invoice Created (invoice.created) | An invoice was made, by you or by a checkout |
Invoice Expired (invoice.expired) | Nothing arrived in time |
Invoice Held for Review (invoice.review) | A payment waits for your review before it counts |
Payment Seen (payment.received) | A transfer was seen on chain, not yet confirmed |
Checkout Completed (checkout.completed) | A checkout session was paid |
Subscription Past Due (subscription.past_due) | A renewal was not paid on time |
Subscription Canceled (subscription.canceled) | A subscription was canceled; it may run to the end of its period |
Access Granted (entitlement.granted) | A buyer was given access to a product |
Access Revoked (entitlement.revoked) | A buyer's access to a product ended |
License Key Issued (license.created) | A license key was issued for a purchase |
Credits Low (credits.low) | A customer's credits fell to the low-balance threshold |
Deliver on Invoice Paid. Put your own order or user ID in the invoice's metadata when you create it; it comes back on every event about that invoice. Each event has a unique id, and Perly Pay retries a delivery that is not answered for up to 72 hours, so a step that must happen once can skip an id it has already seen.
sk_live_… key that is a public https address, so n8n has to be reachable from the internet.Every delivery's Perly-Signature is checked against the raw body before the workflow starts; a bad one is answered 401 and starts nothing. Every other delivery is claimed once from Perly Pay with your key, and Perly Pay's copy is what runs: the same delivery posted again starts nothing. The webhook's signing secret stays in the workflow's static data, never in a node's output.
What buyers pay with
The buyer picks a coin and network on the payment page and pays from any wallet. The money goes straight to yours.
| Coin | Networks |
|---|---|
| BTC | Bitcoin |
| USDC | Base, Arbitrum, Optimism and Ethereum |
| USDT0 | Arbitrum and Optimism |
| USDT | Ethereum and TRON |
Test
With a test key, create an invoice (with the node, or in the dashboard) and pay it with test coins, or from the API with the invoice's id — an HTTP Request node will do:
The trigger then receives invoice.fulfilled as it would for a real payment.
Go live
- Turn on live mode in Perly Pay and connect your wallet's public keys.
- Add a credential with a
sk_live_…key and switch the workflow's Perly Pay nodes to it. Activating the workflow adds the live webhook. - Pay one small real invoice and watch it arrive.