Primeiros passos

Início rápido com npx

Um comando configura o Perly Pay no seu projeto: a rota de checkout, a rota do webhook com verificação de assinatura, um botão Pay e a sua chave de teste.

Ver como Markdown

npx perly-pay init lê o seu projeto, escreve código para o framework dele e deixa você a um clique de um pagamento de teste. Ele só configura o modo de teste; a produção é ativada no painel.

Execute

bash

npx perly-pay init

Ele detecta o framework e o gerenciador de pacotes, abre Dashboard → Developers e pede uma chave de teste (sk_test_…). Uma chave de produção é recusada.

O que ele escreve

Framework	Como detecta	Arquivos
Next.js (App Router)	`next`	`lib/perly-pay.ts`, `app/api/perly-pay/checkout/route.ts`, `app/api/perly-pay/webhook/route.ts`, `components/PayButton.tsx`, `app/perly-pay/page.tsx`
Express	`express`	`lib/perly-pay.js`, `routes/perly-pay.js`
Hono	`hono`	`lib/perly-pay.ts`, `routes/perly-pay.ts`
Laravel	`artisan`, `laravel/framework`	`app/Http/Controllers/PerlyPayController.php`, `routes/perly-pay.php`, `config/perly-pay.php`, `resources/views/perly-pay/button.blade.php`
Node.js	qualquer outro `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript ou JavaScript, módulos ES ou CommonJS, como o seu projeto, e em src/ se o seu código está lá. npm, pnpm, yarn, bun e Composer.

Checkout. O botão envia um formulário para /perly-pay/checkout (/api/perly-pay/checkout no Next.js). Ele abre uma fatura e leva o comprador a pagá-la.
Webhook. /perly-pay/webhook verifica Perly-Signature sobre o corpo bruto. Com invoice.fulfilled, chama grantAccess(), o único TODO que você escreve.
Planos. Vendas únicas e pacotes de créditos, em PLANS no início do módulo principal. O plano, os créditos dele e o seu id de usuário vão nos metadados da fatura e voltam no webhook.
Chaves. PERLY_PAY_SECRET_KEY e PERLY_PAY_WEBHOOK_SECRET em .env.local (Next.js) ou .env, e o arquivo no .gitignore. Se o git já rastreia esse arquivo, o init não escreve a chave nele e diz como parar de rastreá-lo.

O init nunca substitui um arquivo ou um valor que já existe. O --force substitui.

Conecte o webhook

O Perly Pay precisa alcançar o endereço do webhook. Adicione-o em Dashboard → Developers → Webhooks para invoice.fulfilled e cole o segredo whsec_… dele em PERLY_PAY_WEBHOOK_SECRET. Ou deixe o init fazer as duas coisas:

bash

npx perly-pay init --webhook-url https://your-app.example/perly-pay/webhook

Num notebook, um túnel dá a você um endereço público: cloudflared tunnel --url http://localhost:3000. Mais em Webhooks.

Um pagamento no modo de teste

1
Inicie o seu app
Express e Node leem o .env com node --env-file=.env ou dotenv.
2
Abra /perly-pay
Clique em Pay with crypto. Você está no checkout.
3
Simulate payment
A fatura passa a paga e depois a entregue. Veja Modo de teste.
4
Veja o grantAccess agir
Seu webhook recebe invoice.fulfilled. Agora escreva o que ele libera.

Com um assistente de IA

--yes não pergunta nada, então o Claude Code, o Cursor ou o Codex podem executar por você. Passe a chave e o que você vende:

bash

npx perly-pay init --yes --key sk_test_… --product "Logo review" --amount 4900

--json imprime um resultado que o assistente consegue ler.

Opções

Flag	O que faz
`--yes`, `-y`	Sem perguntas. Para assistentes de IA e scripts.
`--framework <name>`	`next`, `express`, `hono`, `laravel` ou `node`, se ele não acertou.
`--key <sk_test_…>`	Sua chave de teste. Por padrão: `PERLY_PAY_SECRET_KEY`, ou ele pergunta.
`--webhook-url <url>`	Registra o endereço para `invoice.fulfilled` e guarda o segredo dele.
`--product <name>`, `--amount <cents>`, `--currency <code>`	O que você vende, em USD ou EUR. `--amount 4900` é $49.00.
`--install`	Também instala o SDK. Senão, imprime o comando.
`--force`	Substitui arquivos e valores que já existem.
`--plugin`, `--mcp`	Imprime como adicionar o plugin do Claude Code e o servidor `perly-pay-mcp`.
`--dry-run`	Diz o que faria, sem escrever nada.
`--json`	Imprime o resultado como JSON.
`--api <origin>`, `--dir <path>`	Outro Perly Pay (local), outra pasta.

Produção

Conecte as chaves reais da sua carteira em Dashboard → Wallets.
Crie uma chave de produção (sk_live_…) e um webhook de produção.
Configure-os onde o seu app roda. O código continua igual. O resto da API está nos SDKs.