https://github.com/fluvpay/openapi
Especificação OpenAPI pública (v1) do gateway de pagamentos PIX da FluvPay. Cobranças, saques, transferências e webhooks.
https://github.com/fluvpay/openapi
brazil fintech fluvpay openapi payment-gateway payments pix rest-api sdk webhooks
Last synced: 25 days ago
JSON representation
Especificação OpenAPI pública (v1) do gateway de pagamentos PIX da FluvPay. Cobranças, saques, transferências e webhooks.
- Host: GitHub
- URL: https://github.com/fluvpay/openapi
- Owner: fluvpay
- License: mit
- Created: 2026-06-08T02:59:14.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-06-08T04:58:49.000Z (25 days ago)
- Last Synced: 2026-06-08T05:11:54.696Z (25 days ago)
- Topics: brazil, fintech, fluvpay, openapi, payment-gateway, payments, pix, rest-api, sdk, webhooks
- Homepage: https://fluvpay.com
- Size: 120 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
API de pagamentos PIX para desenvolvedores. Cobranças, saques, transferências internas e webhooks por uma API REST simples e previsível.
Site
·
Documentação
·
Especificação
·
Comunidade
·
Suporte
---
## Sobre
A **FluvPay** é um gateway de pagamentos PIX voltado para desenvolvedores. Este repositório
contém a **especificação OpenAPI 3.1 pública** da API (a fonte de verdade do contrato) e é a
base para gerar clientes, importar coleções e validar integrações.
Estamos na **v1**. Toda a API vive sob o prefixo `/api/v1`, e novos recursos entram aqui,
sempre na v1, de forma retrocompatível.
- **Base URL:** `https://api.fluvpay.com/api/v1`
- **Especificação:** [`openapi.yaml`](openapi.yaml) e [`openapi.json`](openapi.json)
- **Documentação:** https://docs.fluvpay.com
## Recursos
| Recurso | O que faz |
|---|---|
| **Cobranças** | Cria, consulta e lista cobranças PIX com QR Code e copia-e-cola |
| **Transações** | Extrato financeiro consolidado de entradas e saídas |
| **Saques** | Envia PIX da sua conta para uma chave PIX |
| **Transferências internas** | Move saldo entre contas FluvPay |
| **Webhooks** | Eventos assinados (HMAC) para você reagir a pagamentos em tempo real |
| **Sandbox** | Ambiente de teste completo, sem mover dinheiro de verdade |
## Início rápido
Toda chamada usa sua API Key no header `Authorization`. O ambiente é definido pelo prefixo
da chave: `fluv_live_` para produção e `fluv_test_` para o sandbox.
Criar uma cobrança PIX:
```bash
curl -X POST https://api.fluvpay.com/api/v1/charges/ \
-H "Authorization: Bearer fluv_test_sua_chave" \
-H "Idempotency-Key: 4f1a9c2e-1b7d-4a3e-9b2c-7e6f5d4c3b2a" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 4990,
"description": "Pedido #1042",
"customer": { "name": "Maria Souza", "email": "maria@exemplo.com" }
}'
```
Resposta:
```json
{
"id": "chg_01J9X8K2P3Q4R5S6T7U8V9W0XY",
"amount_cents": 4990,
"currency": "BRL",
"status": "pending",
"payment_method": "pix",
"pix_qr_code": "data:image/png;base64,iVBORw0KGgo...",
"pix_copy_paste": "00020126580014BR.GOV.BCB.PIX...",
"net_amount_cents": 4965,
"created_at": "2026-06-08T12:00:00Z"
}
```
Mostre o `pix_copy_paste` ou renderize o `pix_qr_code`, e aguarde o evento `charge.paid`
no seu webhook para confirmar o pagamento.
## Autenticação e escopos
```
Authorization: Bearer fluv_live_sua_chave
```
As chaves possuem escopos, e cada endpoint exige o seu:
| Escopo | Permite |
|---|---|
| `payments.create` | Criar cobranças |
| `payments.read` | Ler e listar cobranças |
| `withdrawals.create` | Criar saques e transferências internas |
| `withdrawals.read` | Ler e listar saques |
| `transfers.read` | Ler e listar transferências internas |
## Idempotência
As operações de escrita (criar cobrança, saque e transferência) aceitam o header
`Idempotency-Key`. Reenviar a mesma chave devolve a resposta original, em vez de criar um
recurso duplicado. Reusar a chave com um payload diferente retorna `409 IDEMPOTENCY_CONFLICT`.
## Webhooks
A FluvPay envia cada evento ao seu endpoint com os headers `X-FluvPay-Event`,
`X-FluvPay-Timestamp`, `X-FluvPay-Delivery-Id` e `X-FluvPay-Signature`.
A assinatura vem no formato `v1=`, onde:
```
hex = HMAC_SHA256(segredo, "{timestamp}." + corpo_cru)
```
O `segredo` é o `whsec_...` exibido na criação do webhook. Sempre verifique a assinatura
(comparando em tempo constante, sobre o corpo cru) antes de processar o evento.
Eventos disponíveis:
```
charge.created charge.paid charge.expired charge.cancelled charge.refunded
payout.created payout.completed payout.failed
```
## Erros
Todos os erros seguem o mesmo envelope, com um `code` canônico e um `trace_id` para
correlação nos logs:
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Dados inválidos",
"details": [{ "field": "amount_cents", "message": "...", "type": "..." }],
"trace_id": "01J9X8K2P3Q4R5S6T7U8V9W0XY"
}
}
```
## SDKs oficiais
SDKs idiomáticos, gerados a partir desta especificação, com tipagem forte, idempotência
automática, retries seguros e verificação de webhook embutida.
Node.js
Python
PHP
Go
Java
Ruby
.NET
Clique no logo para abrir o repositório. O de Node.js é TypeScript-first.
## Usar a especificação
A `openapi.yaml` é a fonte de verdade do contrato. Com ela você pode:
- **Visualizar** em qualquer editor OpenAPI (Swagger Editor, Redocly, Stoplight).
- **Importar** no Postman ou Insomnia para testar os endpoints.
- **Gerar um cliente** na sua linguagem com o `openapi-generator`:
```bash
npx @openapitools/openapi-generator-cli generate \
-i https://raw.githubusercontent.com/fluvpay/OpenAPI/main/openapi.yaml \
-g python \
-o ./fluvpay-client
```
## Ambientes
| Ambiente | Como ativar | Move dinheiro? |
|---|---|---|
| **Sandbox** | API Key com prefixo `fluv_test_` | Não. Gera dados de teste. |
| **Produção** | API Key com prefixo `fluv_live_` | Sim. |
A mesma base URL atende os dois. O ambiente é decidido pelo prefixo da chave.
## Comunidade
Dúvidas, novidades e contato direto com o time da FluvPay no nosso Discord:
## Segurança
Encontrou uma vulnerabilidade? Não abra uma issue pública. Use o canal de divulgação
responsável descrito em https://docs.fluvpay.com.
## Licença
Distribuído sob a licença MIT. Veja [`LICENSE`](LICENSE).
---
Feito pela FluvPay · © 2026