指南

Make

把付款接入任何 Make 场景：已付账单、退款、订阅和客户的即时触发器；创建和查找账单与付款链接的模块。

Perly Pay 应用把你的付款带进 Make。一张已付账单可以填写表格、更新 CRM 或授予 Discord 角色；一个表单可以创建账单并发送付款页。无需托管任何东西，也没有代码。

测试密钥和正式密钥是两个连接。使用测试连接的场景只能看到测试付款。

连接

1
获取密钥
在 Perly Pay 中：Dashboard → Developers → API keys。sk_test_… 用于测试模式，sk_live_… 用于真实资金。
2
把 Perly Pay 加入场景
该应用正在上架 Make 应用列表。在上架之前，请联系我们获取邀请链接；打开一次，之后添加模块时搜索 Perly Pay。
3
连接
Add 一个连接并粘贴密钥。命名时区分测试和正式。

即时触发器

模块	时机	事件
Watch paid invoices	已全额付款，付款人已核查。可以开通访问或发货了。	`invoice.fulfilled`
Watch underpaid invoices	买家发送的金额少于账单要求。	`invoice.underpaid`
Watch opened refunds	你发起了一笔退款。	`refund.requested`
Watch confirmed refunds	你发出的退款已在链上确认。	`refund.confirmed`
Watch started subscriptions	一个订阅开始了。	`subscription.created`
Watch renewed subscriptions	订阅者支付了下一个周期。	`subscription.renewed`
Watch ended subscriptions	订阅已结束。可以收回访问权限了。	`subscription.ended`
Watch new customers	一位新买家。	`customer.created`

在 Make 中为触发器添加 Webhook 时，Dashboard → Developers → Webhooks 里会出现一个类似 Make: Paid invoices 的 Webhook；在 Make 中删除它，它也随之消失。场景运行前，Make 会用你的密钥向 Perly Pay 领取每次投递，而 Perly Pay 每次投递只交出一次：不是来自 Perly Pay 的请求，或被再次发送的请求，都不会触发任何东西。每个 Webhook 都占用该模式 16 个名额中的一个。

每个触发器都会给出事件及其对应的对象 — 账单、退款、订阅或客户 — 与 API 中的形式一致。法币金额以分为单位（total 4900 即 49.00）：在映射中除以 100。币种金额以该币的最小单位表示，旁边附有 decimals。

模块

模块	需要提供	你会得到
Create an invoice	金额（如 49.00）、描述；可选币种、客户邮箱、退款地址、元数据	一张带付款页（Payment page URL）的账单，发给买家
Create a payment link	价格，或新商品的名称和金额	一个出售该商品的页面 — 随处分享
Get an invoice	账单 ID	它的状态、已到账金额、付款页
Search customers	邮箱，或留空以获取全部	客户列表，最新的在前
Make an API call	一个路径（如 `/invoices`）、一个方法，需要时再加 JSON 正文	API 的原样响应，用于其他模块做不到的事

配方

付款 → Google Sheets 中的一行

1
触发器
Perly Pay → Watch paid invoices。添加 Webhook；运行一次场景并支付一张测试账单，让 Make 认识这些字段。
2
操作
Google Sheets → Add a Row，表格的列可以是日期、邮箱、金额、币种。
3
映射
日期 → Invoice: Paid at，邮箱 → Customer email，金额 → Total (cents) / 100，币种 → Payment: Coin。开启。

付款 → Discord 角色

Discord 需要知道是谁付的款。创建账单时把买家的 Discord ID 放进账单，账单付清时再读出来。

1
场景 1：账单
触发器：带邮箱和 Discord ID 的注册表单。Perly Pay → Create an invoice，元数据键 discord_user_id，值为表单中的回答。然后把 Payment page URL 发给买家。
2
场景 2：角色
Perly Pay → Watch paid invoices。Discord → Add a Role to a Member（或向 Discord Make an API call）：你的服务器、角色，成员 = Invoice: Metadata → discord_user_id。
3
收回角色
对于订阅，Watch ended subscriptions 以同样方式移除角色。

测试

在测试连接上创建一张账单（用模块或在控制台中），然后用测试币支付，或按账单 ID 通过 API 支付：

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

几秒钟内场景就会运行。它的 History 显示每次运行和收到的内容。

真实付款

在 Perly Pay 中开启正式模式，并连接钱包公钥。
添加一个使用 sk_live_… 密钥的连接。在每个场景中，用它为触发器添加新的 Webhook，并把其他 Perly Pay 模块切换到它。
支付一张小额真实账单，看着它到账。