# Pagnovo API Documentation

> Documentação pública da API REST da Pagnovo — processadora de pagamentos brasileira focada em PIX. Cobre cash-in e cash-out via API direta (checkout transparente) e fluxo completo de catálogo + checkout hospedado + assinaturas recorrentes para SaaS, infoprodutos e cursos.

Convenções da API:
- Autenticação por HTTP Basic Auth com secret key (`Authorization: Basic base64(secret:SUA_SECRET_KEY)`).
- Todos os valores monetários em **centavos** (R$ 1,00 = 100). Cupons em PERCENTAGE e juros usam **basis points** (1.000 = 10%). Multas em FIXED são em centavos.
- Paginação **0-indexed** (`page=0` é a primeira página). Limit default 20, máximo 100.
- Toda resposta carrega header `x-trace-id` para correlação com logs do servidor.
- **Scopes por chave**: cada chave de API carrega um conjunto de permissões. As rotas `/v2/*` exigem o scope do recurso — leitura (`GET`) pede `view<Recurso>`, escrita (`POST`/`PATCH`/`DELETE`) pede `manage<Recurso>`. Sem o scope → **403 "Unauthorized Permissions"**. Lista completa na seção Autenticação.
- **IP allowlist (cash-out e estorno)**: opcional. Se houver IPs cadastrados (em Configurações → IPs whitelist), apenas eles podem chamar `createWithdraw` e `createRefund`; IP fora da lista → **400 "IP unauthorized"**. Lista vazia = sem restrição. Recomendado travar em produção.
- **Sandbox/Dev mode**: cadastro via `/auth/signup-light` cria conta TEST + LIVE espelho. Sandbox usa chave `sk_test_*` e ambiente `TEST`. Cap de 30 operações/dia (Tx + Withdraw + Refund). Outcome determinístico por valor (R$ 10,00 aprova / 10,01 recusa / 10,02 incosistente / 10,04 chargeback / 10,05 estorna / 10,06 bloqueio). Após KYC aprovado, upgrade para chave LIVE.
- **Webhooks V1 + V2 coexistem**: V1 (`postbackUrl` per-transação, payload camelCase plano) e V2 (Webhook global cadastrado em Configurações ou via `/v2/webhooks`, payload com envelope `{ event, environment, payload }`) rodam em paralelo. Se ambos configurados, endpoint recebe 2 POSTs por evento — handler precisa ser idempotente.

## Guias por caso de uso

- [Pagamentos via API](https://pay.pagnovo.com/docs/api-payments-guide): Use quando você tem sua própria UI (app, dashboard, marketplace, wallet, P2P, iGaming, casa de apostas) e só precisa de PIX cash-in + cash-out via API. Cobre Transações, Saques e Saldo. Não usa catálogo, customer, checkout hospedado, cupom nem assinatura.
- [Catálogo e Assinaturas](https://pay.pagnovo.com/docs/saas-guide): Use para SaaS, infoproduto, curso ou qualquer venda com checkout hospedado e cobrança recorrente. Cobre o modelo Product → Offer → PaymentLink → (Customer + Invoice + Subscription criados automaticamente no checkout).

## Conceitos

- [Autenticação e chaves](https://pay.pagnovo.com/docs/authentication): HTTP Basic Auth, scopes por chave (incluindo os scopes de recurso `view`/`manage` exigidos pelas rotas `/v2/*`), separação de chaves por contexto, IP allowlist opcional para cash-out e estorno, respostas de erro 401/403.
- [Trace ID e debug](https://pay.pagnovo.com/docs/x-trace-id): Como o `x-trace-id` funciona, propagação end-to-end entre sistemas, uso recomendado em produção (capturar, anexar a erros, mostrar ao usuário final, persistir).

## Webhooks

- [Webhooks (visão geral)](https://pay.pagnovo.com/docs/webhooks-overview): O que são webhooks, como funcionam, retry com backoff exponencial.
- [Verificação de assinatura HMAC](https://pay.pagnovo.com/docs/signature-key): Algoritmo (sortObjectKeys + HMAC-SHA256), implementação de referência em TypeScript e Python, erros comuns (re-serialização, comparação não-timing-safe, secret errada).
- [Modelos V1 e V2](https://pay.pagnovo.com/docs/webhook-configuration): V1 (`postbackUrl` per-transação, payload camelCase plano) e V2 (Webhook global subscrito a eventos específicos) **rodam em paralelo** — não são mutuamente exclusivos. Tabela comparativa + idempotência.
- [Payload v1 (legado)](https://pay.pagnovo.com/docs/webhook-v1): Estrutura camelCase plana, status de transação (incluindo INCOSISTENT só em transaction), status de saque (sem INCOSISTENT), status de infração.
- [Payload v2 (moderno)](https://pay.pagnovo.com/docs/webhook-v2): Envelope `{ event, environment, payload }` em **todos** os eventos (cash-in/out, infração e `subscription.*`). Snake_case, ISPB de pagador/recebedor. **Eventos suportados (12)**: `cashin.paid`, `cashin.refunded`, `cashout.success`, `cashout.failed`, `cashout.returned`, `infraction.updated`, `subscription.created`, `subscription.activated`, `subscription.paused`, `subscription.canceled`, `subscription.past_due`, `subscription.expired`. **CHARGEBACK e BLOCKED viram `infraction.updated`** (não eventos próprios). **REJECTED não dispara webhook V2** (só V1 e response HTTP).

## Webhooks (CRUD via API)

- [GET /v2/webhooks](https://pay.pagnovo.com/docs/api/list-webhooks): Lista webhooks globais ativos no environment atual (decidido pela chave).
- [POST /v2/webhooks](https://pay.pagnovo.com/docs/api/create-webhook): Cria endpoint. Retorna `secret` plain-text **uma única vez** (guarde pra validar HMAC). Body: `{ url, description?, events[] }`. URL exige HTTPS em prod. SSRF protection bloqueia IPs privados/loopback/AWS metadata.
- [PATCH /v2/webhooks/:id](https://pay.pagnovo.com/docs/api/update-webhook): Atualiza `url`, `description`, `events`, `active`. Pra rotacionar secret use endpoint dedicado.
- [DELETE /v2/webhooks/:id](https://pay.pagnovo.com/docs/api/delete-webhook): Remove. Deliveries antigos ficam acessíveis por 15 dias.
- [POST /v2/webhooks/:id/rotate-secret](https://pay.pagnovo.com/docs/api/rotate-webhook-secret): Gera novo secret + retorna plain-text. Secret anterior válido por 24h (grace period — receivers aceitam ambos).
- [POST /v2/webhooks/:id/test](https://pay.pagnovo.com/docs/api/test-webhook): POST inline com payload fake. **Rate limit 1/30s** por webhook. Retorna statusCode, durationMs, responseBody. SSRF protection validate em runtime.
- [GET /v2/webhooks/:id/deliveries](https://pay.pagnovo.com/docs/api/list-webhook-deliveries): Histórico (15d retention). **Rate limit 30/min**. Cache no seu lado (~30s) recomendado pra dashboards.
- [GET /v2/webhooks/:id/metrics](https://pay.pagnovo.com/docs/api/webhook-metrics): Counts e latência agregados (24h, 7d). **Rate limit 10/min** + **cache server-side 60s**.

## Saldo

- [GET /accounts/balance](https://pay.pagnovo.com/docs/api/get-balance): Retorna saldo disponível, em liquidação, depósitos de garantia, bloqueios cautelares e reservas de chargeback. Valores em centavos.

## Transações (Cash-in)

- [POST /transactions/v2/purchase](https://pay.pagnovo.com/docs/api/create-transaction): Cria transação de entrada. PIX retorna BR Code; cartão é autorizado de forma síncrona. Use `restrictPayerDocument: true` para travar a transação ao CPF informado.
- [GET /transactions/:id](https://pay.pagnovo.com/docs/api/get-transaction): Busca por id interno, externalId ou end2End do PIX (parâmetro `searchBy`).
- [POST /transactions/refund/:id](https://pay.pagnovo.com/docs/api/refund-transaction): Estorna uma transação aprovada. PIX devolve imediato; cartão pode levar até 30 dias úteis.

## Saques (Cash-out)

- [POST /withdraws/cash-out](https://pay.pagnovo.com/docs/api/cashout-pix-key): Saque via chave PIX (DICT). Use `restrictReceiverDocument: true` para validar o CPF retornado pelo DICT.
- [POST /withdraws/cash-out/qrc](https://pay.pagnovo.com/docs/api/cashout-qrcode): Saque pagando um BR Code copia-e-cola.
- [GET /withdraws/collect/:id](https://pay.pagnovo.com/docs/api/get-withdraw): Estado completo de um saque com timestamps por evento do ciclo de vida.

## Clientes

- [POST /v2/customers](https://pay.pagnovo.com/docs/api/create-customer): Cria cliente. `document` (CPF/CNPJ) é único por conta e imutável após criação.
- [GET /v2/customers](https://pay.pagnovo.com/docs/api/list-customers): Lista paginada com busca em name/email/document.
- [GET /v2/customers/:id](https://pay.pagnovo.com/docs/api/get-customer): Customer completo + stats (`activeSubscriptions`, `openInvoicesCount`, `paidInvoicesCount`, `paidAmountTotal` em centavos).
- [PATCH /v2/customers/:id](https://pay.pagnovo.com/docs/api/update-customer): Atualiza campos. `document` não é editável.
- [DELETE /v2/customers/:id](https://pay.pagnovo.com/docs/api/delete-customer): Arquiva. Bloqueia se houver subscription ativa.
- [GET /v2/customers/:id/history](https://pay.pagnovo.com/docs/api/customer-history): View 360° — stats (`ltv`, `ticketMedio`, `overdueAmount`, `totalRefunded` em centavos) + listas de subscriptions, invoices, transactions, refunds.

## Cupons

- [Cupons (visão geral)](https://pay.pagnovo.com/docs/coupons-overview): Whitelist de Offers (cada cupom só funciona nas Offers autorizadas), `discountValue` polimórfico (basis points em PERCENTAGE, centavos em FIXED), ciclo ACTIVE→PAUSED→ARCHIVED, snapshot fields imutáveis após primeiro uso.
- [POST /v2/coupons](https://pay.pagnovo.com/docs/api/create-coupon)
- [GET /v2/coupons](https://pay.pagnovo.com/docs/api/list-coupons)
- [GET /v2/coupons/:id](https://pay.pagnovo.com/docs/api/get-coupon): inclui `allowedOffers[]` e `stats.totalDiscounted` em centavos.
- [PATCH /v2/coupons/:id](https://pay.pagnovo.com/docs/api/update-coupon): não permite editar `discountType` ou `discountValue`.
- [POST /v2/coupons/:id/pause](https://pay.pagnovo.com/docs/api/pause-coupon)
- [POST /v2/coupons/:id/resume](https://pay.pagnovo.com/docs/api/resume-coupon)
- [DELETE /v2/coupons/:id](https://pay.pagnovo.com/docs/api/archive-coupon): arquiva (idempotente).
- [GET /v2/coupons/:id/redemptions](https://pay.pagnovo.com/docs/api/list-redemptions)
- [POST /v2/coupons/:id/offers](https://pay.pagnovo.com/docs/api/add-coupon-offers): adiciona Offers à whitelist do cupom.
- [DELETE /v2/coupons/:id/offers/:offerId](https://pay.pagnovo.com/docs/api/remove-coupon-offer)

## Produtos

- [Produtos e Ofertas (visão geral)](https://pay.pagnovo.com/docs/products-offers-overview): Product é catálogo; Offer é variação de preço e ciclo. Editar campos de preço/ciclo de uma Offer com dependentes ativos é bloqueado (padrão recomendado: criar Offer nova e desativar a antiga).
- [POST /v2/products](https://pay.pagnovo.com/docs/api/create-product): cria sem imagem (`imageUrl` não aceito no JSON).
- [GET /v2/products](https://pay.pagnovo.com/docs/api/list-products)
- [GET /v2/products/:id](https://pay.pagnovo.com/docs/api/get-product)
- [PATCH /v2/products/:id](https://pay.pagnovo.com/docs/api/update-product): `imageUrl` não editável aqui.
- [DELETE /v2/products/:id](https://pay.pagnovo.com/docs/api/delete-product): bloqueia se houver Offer vinculada.
- [GET /v2/products/:id/offers](https://pay.pagnovo.com/docs/api/list-product-offers)
- [POST /v2/products/:id/image](https://pay.pagnovo.com/docs/api/upload-product-image): multipart, JPG/PNG/WebP até 5MB. Sharp redimensiona pra 1024px + WebP q85. Hospedado no nosso S3 com URL pública fixa.
- [DELETE /v2/products/:id/image](https://pay.pagnovo.com/docs/api/delete-product-image): remove do S3 + zera campo.

## Ofertas

- [POST /v2/offers](https://pay.pagnovo.com/docs/api/create-offer): One-time (sem billingCycle) ou recurring (MONTHLY, YEARLY etc). `deliveryPdfUrl` não aceito no JSON.
- [GET /v2/offers](https://pay.pagnovo.com/docs/api/list-offers): filtros por productId, active, kind (recurring/oneoff). `deliveryPdfUrl` retorna como signed URL temporária.
- [GET /v2/offers/:id](https://pay.pagnovo.com/docs/api/get-offer): inclui `stats.canEditSnapshotFields`. PDF retorna como signed URL nova de 1h.
- [PATCH /v2/offers/:id](https://pay.pagnovo.com/docs/api/update-offer): campos amount/billingCycle/billingCycleCount/maxCycles/trialDays bloqueiam se há subscriptions/paymentLinks ativos. `deliveryPdfUrl` não editável aqui.
- [DELETE /v2/offers/:id](https://pay.pagnovo.com/docs/api/delete-offer)
- [POST /v2/offers/:id/delivery-pdf](https://pay.pagnovo.com/docs/api/upload-offer-pdf): multipart, PDF até 5MB. Hospedado no S3 como objeto privado. Acessível via signed URL temporária retornada nas consultas.
- [DELETE /v2/offers/:id/delivery-pdf](https://pay.pagnovo.com/docs/api/delete-offer-pdf): remove do S3 + zera campo.

## Links de pagamento (Quick Links)

- [Links de pagamento (visão geral)](https://pay.pagnovo.com/docs/quick-links-overview): URL pública de cobrança avulsa. O cliente paga e é gerada uma **Transaction** diretamente (sem Customer/Invoice/Subscription — esse fluxo recorrente é o do Checkout de Offer). Cobrança one-time simples (doação, mensalidade, link rápido).
- [POST /v2/quick-links](https://pay.pagnovo.com/docs/api/create-quick-link): cria com slug auto-gerado ou manual.
- [GET /v2/quick-links](https://pay.pagnovo.com/docs/api/list-quick-links): filtros status, offerId, productId.
- [GET /v2/quick-links/:id](https://pay.pagnovo.com/docs/api/get-quick-link)
- [GET /v2/quick-links/:id/transactions](https://pay.pagnovo.com/docs/api/list-quick-link-transactions): transações geradas pelo link.
- [PATCH /v2/quick-links/:id](https://pay.pagnovo.com/docs/api/update-quick-link)
- [POST /v2/quick-links/:id/pause](https://pay.pagnovo.com/docs/api/pause-quick-link)
- [POST /v2/quick-links/:id/resume](https://pay.pagnovo.com/docs/api/resume-quick-link)
- [POST /v2/quick-links/:id/duplicate](https://pay.pagnovo.com/docs/api/duplicate-quick-link): clona com novo slug.
- [DELETE /v2/quick-links/:id](https://pay.pagnovo.com/docs/api/archive-quick-link): arquiva.

## Subscriptions

- [Subscriptions (visão geral)](https://pay.pagnovo.com/docs/subscriptions-overview): Snapshot pattern (valores copiados da Offer no momento da criação), ciclo de cobrança (`daysBeforeDueToBill`, `daysBeforeDueToNotify`), multas FIXED (centavos) ou PERCENTAGE (basis points), juros `interestRatePerMonth` (basis points), pause vs cancel, `maxCycles` vs `expiresAt`.
- [POST /v2/subscriptions](https://pay.pagnovo.com/docs/api/create-subscription): via `offerId` (snapshot) ou standalone (`amount` + `billingCycle` manuais). Campo opcional `description` aparece nas invoices recorrentes geradas (fallback automático se omitido).
- [GET /v2/subscriptions](https://pay.pagnovo.com/docs/api/list-subscriptions): filtros status, customerId, offerId.
- [GET /v2/subscriptions/:id](https://pay.pagnovo.com/docs/api/get-subscription): inclui `stats` (invoicesCount, amountPaidTotal em centavos, openInvoices).
- [GET /v2/subscriptions/:id/invoices](https://pay.pagnovo.com/docs/api/list-subscription-invoices)
- [PATCH /v2/subscriptions/:id](https://pay.pagnovo.com/docs/api/update-subscription): mudanças só valem a partir do próximo ciclo. Invoices já existentes ficam congeladas.
- [POST /v2/subscriptions/:id/pause](https://pay.pagnovo.com/docs/api/pause-subscription): só de ACTIVE/TRIAL/PAST_DUE.
- [POST /v2/subscriptions/:id/resume](https://pay.pagnovo.com/docs/api/resume-subscription): só de PAUSED. Reagenda `nextBillingAt` se passado.
- [POST /v2/subscriptions/:id/cancel](https://pay.pagnovo.com/docs/api/cancel-subscription): final. Cancela em cascata todas as Invoices PENDING/OVERDUE/DRAFT.

## Invoices

- [Invoices (visão geral)](https://pay.pagnovo.com/docs/invoices-overview): Unidade atômica de cobrança. 3 origens (avulsa via POST, via PaymentLink, via Subscription). Estados DRAFT/PENDING/PAID/OVERDUE/REFUNDED/CANCELED/EXPIRED. Items somam com amount (validado em centavos). `hostedUrl` pública para o cliente pagar. Estorno parcial via `mark-refunded`.
- [POST /v2/invoices](https://pay.pagnovo.com/docs/api/create-invoice): avulsa (com ou sem `customerId`) ou vinculada a `subscriptionId` (uso interno).
- [GET /v2/invoices](https://pay.pagnovo.com/docs/api/list-invoices): com `totals.amount` e `totals.amountPaid` agregados (centavos).
- [GET /v2/invoices/:id](https://pay.pagnovo.com/docs/api/get-invoice): inclui `attempts[]` (com `lateFeeApplied`, `interestApplied`) e últimas 20 `notifications`.
- [PATCH /v2/invoices/:id](https://pay.pagnovo.com/docs/api/update-invoice): só DRAFT/PENDING e sem attempt APPROVED.
- [POST /v2/invoices/:id/cancel](https://pay.pagnovo.com/docs/api/cancel-invoice): cancela invoice + attempts PENDING.
- [POST /v2/invoices/:id/mark-refunded](https://pay.pagnovo.com/docs/api/mark-invoice-refunded): só atualiza status para REFUNDED. NÃO executa o estorno PIX em si (responsabilidade do módulo de Refund).
- [POST /v2/invoices/:id/notifications/resend](https://pay.pagnovo.com/docs/api/resend-invoice-notification): reenvia INVOICE_CREATED, INVOICE_REMINDER, INVOICE_OVERDUE, INVOICE_PAID ou INVOICE_CANCELED. Canal suportado hoje: **EMAIL** (SMS e WhatsApp no roadmap).
- [GET /v2/invoices/metrics](https://pay.pagnovo.com/docs/api/invoice-metrics): métricas agregadas por período (`7d`, `30d`, `90d`, `mtd`). Counts, amounts (centavos), payment/default rates, série diária, próximas a vencer, vencidas atuais.