Introdução
O que é a PlugToPay, para quem é e como começar.
A PlugToPay é uma camada de orquestração de pagamentos que roteia transações entre múltiplos gateways (Pagarme, Safe2Pay, PicPay) com fallback automático, cofre de cartões agnóstico e entrega de webhooks com retenção.
Para quem é esta documentação
Esta referência é voltada para desenvolvedores que integram diretamente com a API da PlugToPay via X-API-Key. Para o painel de gestão acesse app.plugtopay.com.
Base URLs
| Ambiente | URL |
|---|---|
| Produção | https://dev.plugtopay.com/api/v1 |
| BFF do painel | /api/plugtopay (proxy Next.js — somente uso interno) |
Todos os exemplos nesta documentação usam a URL de produção diretamente. O BFF é exclusivo para o painel administrativo e não deve ser usado em integrações externas.
Esquemas de autenticação
A API expõe três esquemas distintos:
| Esquema | Header | Quem usa |
|---|---|---|
| Sem autenticação | — | Cadastro, login, callbacks de gateway |
| API Key | X-Client-ID + X-API-Key | Integrações servidor-a-servidor |
| Bearer JWT | Authorization: Bearer <token> | Painel administrativo |
Próximos passos
- Autenticação — obtenha e gerencie suas credenciais.
- Pagamentos — crie transações com cartão ou PIX.
- Idempotência — processe pagamentos com segurança em redes instáveis.
- Webhooks — receba notificações de eventos em tempo real.
- Sub-contas — splits para marketplaces.
- Status — interprete os estados de cada transação.
- Gateways — gateways suportados e lógica de roteamento.