{"id":50665798,"url":"https://github.com/fluvpay/openapi","last_synced_at":"2026-06-08T06:05:30.278Z","repository":{"id":363244378,"uuid":"1262476938","full_name":"fluvpay/OpenAPI","owner":"fluvpay","description":"Especificação OpenAPI pública (v1) do gateway de pagamentos PIX da FluvPay. Cobranças, saques, transferências e webhooks.","archived":false,"fork":false,"pushed_at":"2026-06-08T04:58:49.000Z","size":123,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T05:11:54.696Z","etag":null,"topics":["brazil","fintech","fluvpay","openapi","payment-gateway","payments","pix","rest-api","sdk","webhooks"],"latest_commit_sha":null,"homepage":"https://fluvpay.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluvpay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T02:59:14.000Z","updated_at":"2026-06-08T04:46:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fluvpay/OpenAPI","commit_stats":null,"previous_names":["fluvpay/openapi"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fluvpay/OpenAPI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluvpay%2FOpenAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluvpay%2FOpenAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluvpay%2FOpenAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluvpay%2FOpenAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluvpay","download_url":"https://codeload.github.com/fluvpay/OpenAPI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluvpay%2FOpenAPI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34050264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazil","fintech","fluvpay","openapi","payment-gateway","payments","pix","rest-api","sdk","webhooks"],"created_at":"2026-06-08T06:04:53.338Z","updated_at":"2026-06-08T06:05:30.273Z","avatar_url":"https://github.com/fluvpay.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"FluvPay\" width=\"780\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  API de pagamentos PIX para desenvolvedores. Cobranças, saques, transferências internas e webhooks por uma API REST simples e previsível.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/API-v1-34d399?style=flat-square\u0026labelColor=0a0a0a\" alt=\"API v1\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OpenAPI-3.1-0a0a0a?style=flat-square\u0026logo=openapiinitiative\u0026logoColor=34d399\" alt=\"OpenAPI 3.1\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PIX-instant%C3%A2neo-34d399?style=flat-square\u0026labelColor=0a0a0a\" alt=\"PIX instantâneo\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/licen%C3%A7a-MIT-0a0a0a?style=flat-square\" alt=\"Licença MIT\"\u003e\n  \u003ca href=\"https://discord.gg/5rpHRhTxJB\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-entrar-5865F2?style=flat-square\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://fluvpay.com\"\u003eSite\u003c/a\u003e\n  ·\n  \u003ca href=\"https://docs.fluvpay.com\"\u003eDocumentação\u003c/a\u003e\n  ·\n  \u003ca href=\"openapi.yaml\"\u003eEspecificação\u003c/a\u003e\n  ·\n  \u003ca href=\"https://discord.gg/5rpHRhTxJB\"\u003eComunidade\u003c/a\u003e\n  ·\n  \u003ca href=\"https://docs.fluvpay.com\"\u003eSuporte\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Sobre\n\nA **FluvPay** é um gateway de pagamentos PIX voltado para desenvolvedores. Este repositório\ncontém a **especificação OpenAPI 3.1 pública** da API (a fonte de verdade do contrato) e é a\nbase para gerar clientes, importar coleções e validar integrações.\n\nEstamos na **v1**. Toda a API vive sob o prefixo `/api/v1`, e novos recursos entram aqui,\nsempre na v1, de forma retrocompatível.\n\n- **Base URL:** `https://api.fluvpay.com/api/v1`\n- **Especificação:** [`openapi.yaml`](openapi.yaml) e [`openapi.json`](openapi.json)\n- **Documentação:** https://docs.fluvpay.com\n\n## Recursos\n\n| Recurso | O que faz |\n|---|---|\n| **Cobranças** | Cria, consulta e lista cobranças PIX com QR Code e copia-e-cola |\n| **Transações** | Extrato financeiro consolidado de entradas e saídas |\n| **Saques** | Envia PIX da sua conta para uma chave PIX |\n| **Transferências internas** | Move saldo entre contas FluvPay |\n| **Webhooks** | Eventos assinados (HMAC) para você reagir a pagamentos em tempo real |\n| **Sandbox** | Ambiente de teste completo, sem mover dinheiro de verdade |\n\n## Início rápido\n\nToda chamada usa sua API Key no header `Authorization`. O ambiente é definido pelo prefixo\nda chave: `fluv_live_` para produção e `fluv_test_` para o sandbox.\n\nCriar uma cobrança PIX:\n\n```bash\ncurl -X POST https://api.fluvpay.com/api/v1/charges/ \\\n  -H \"Authorization: Bearer fluv_test_sua_chave\" \\\n  -H \"Idempotency-Key: 4f1a9c2e-1b7d-4a3e-9b2c-7e6f5d4c3b2a\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"amount_cents\": 4990,\n    \"description\": \"Pedido #1042\",\n    \"customer\": { \"name\": \"Maria Souza\", \"email\": \"maria@exemplo.com\" }\n  }'\n```\n\nResposta:\n\n```json\n{\n  \"id\": \"chg_01J9X8K2P3Q4R5S6T7U8V9W0XY\",\n  \"amount_cents\": 4990,\n  \"currency\": \"BRL\",\n  \"status\": \"pending\",\n  \"payment_method\": \"pix\",\n  \"pix_qr_code\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"pix_copy_paste\": \"00020126580014BR.GOV.BCB.PIX...\",\n  \"net_amount_cents\": 4965,\n  \"created_at\": \"2026-06-08T12:00:00Z\"\n}\n```\n\nMostre o `pix_copy_paste` ou renderize o `pix_qr_code`, e aguarde o evento `charge.paid`\nno seu webhook para confirmar o pagamento.\n\n## Autenticação e escopos\n\n```\nAuthorization: Bearer fluv_live_sua_chave\n```\n\nAs chaves possuem escopos, e cada endpoint exige o seu:\n\n| Escopo | Permite |\n|---|---|\n| `payments.create` | Criar cobranças |\n| `payments.read` | Ler e listar cobranças |\n| `withdrawals.create` | Criar saques e transferências internas |\n| `withdrawals.read` | Ler e listar saques |\n| `transfers.read` | Ler e listar transferências internas |\n\n## Idempotência\n\nAs operações de escrita (criar cobrança, saque e transferência) aceitam o header\n`Idempotency-Key`. Reenviar a mesma chave devolve a resposta original, em vez de criar um\nrecurso duplicado. Reusar a chave com um payload diferente retorna `409 IDEMPOTENCY_CONFLICT`.\n\n## Webhooks\n\nA FluvPay envia cada evento ao seu endpoint com os headers `X-FluvPay-Event`,\n`X-FluvPay-Timestamp`, `X-FluvPay-Delivery-Id` e `X-FluvPay-Signature`.\n\nA assinatura vem no formato `v1=\u003chex\u003e`, onde:\n\n```\nhex = HMAC_SHA256(segredo, \"{timestamp}.\" + corpo_cru)\n```\n\nO `segredo` é o `whsec_...` exibido na criação do webhook. Sempre verifique a assinatura\n(comparando em tempo constante, sobre o corpo cru) antes de processar o evento.\n\nEventos disponíveis:\n\n```\ncharge.created   charge.paid       charge.expired   charge.cancelled   charge.refunded\npayout.created   payout.completed  payout.failed\n```\n\n## Erros\n\nTodos os erros seguem o mesmo envelope, com um `code` canônico e um `trace_id` para\ncorrelação nos logs:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Dados inválidos\",\n    \"details\": [{ \"field\": \"amount_cents\", \"message\": \"...\", \"type\": \"...\" }],\n    \"trace_id\": \"01J9X8K2P3Q4R5S6T7U8V9W0XY\"\n  }\n}\n```\n\n## SDKs oficiais\n\nSDKs idiomáticos, gerados a partir desta especificação, com tipagem forte, idempotência\nautomática, retries seguros e verificação de webhook embutida.\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-node\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/nodejs/nodejs-original.svg\" alt=\"Node.js\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eNode.js\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-python\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg\" alt=\"Python\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003ePython\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-php\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/php/php-original.svg\" alt=\"PHP\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003ePHP\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-go\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/go/go-original-wordmark.svg\" alt=\"Go\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eGo\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-java\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/java/java-original.svg\" alt=\"Java\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eJava\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-ruby\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/ruby/ruby-original.svg\" alt=\"Ruby\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eRuby\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\" width=\"115\"\u003e\u003ca href=\"https://github.com/fluvpay/fluvpay-dotnet\"\u003e\u003cimg height=\"46\" src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/dotnetcore/dotnetcore-original.svg\" alt=\".NET\"\u003e\u003c/a\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e.NET\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eClique no logo para abrir o repositório. O de Node.js é TypeScript-first.\u003c/sub\u003e\u003c/p\u003e\n\n## Usar a especificação\n\nA `openapi.yaml` é a fonte de verdade do contrato. Com ela você pode:\n\n- **Visualizar** em qualquer editor OpenAPI (Swagger Editor, Redocly, Stoplight).\n- **Importar** no Postman ou Insomnia para testar os endpoints.\n- **Gerar um cliente** na sua linguagem com o `openapi-generator`:\n\n```bash\nnpx @openapitools/openapi-generator-cli generate \\\n  -i https://raw.githubusercontent.com/fluvpay/OpenAPI/main/openapi.yaml \\\n  -g python \\\n  -o ./fluvpay-client\n```\n\n## Ambientes\n\n| Ambiente | Como ativar | Move dinheiro? |\n|---|---|---|\n| **Sandbox** | API Key com prefixo `fluv_test_` | Não. Gera dados de teste. |\n| **Produção** | API Key com prefixo `fluv_live_` | Sim. |\n\nA mesma base URL atende os dois. O ambiente é decidido pelo prefixo da chave.\n\n## Comunidade\n\nDúvidas, novidades e contato direto com o time da FluvPay no nosso Discord:\n\n\u003cp\u003e\n  \u003ca href=\"https://discord.gg/5rpHRhTxJB\"\u003e\u003cimg src=\"https://img.shields.io/badge/entrar%20no%20Discord-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Entrar no Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Segurança\n\nEncontrou uma vulnerabilidade? Não abra uma issue pública. Use o canal de divulgação\nresponsável descrito em https://docs.fluvpay.com.\n\n## Licença\n\nDistribuído sob a licença MIT. Veja [`LICENSE`](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  Feito pela \u003ca href=\"https://fluvpay.com\"\u003eFluvPay\u003c/a\u003e · © 2026\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluvpay%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluvpay%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluvpay%2Fopenapi/lists"}