# Super Finance API Documentation

> Documentação pública das APIs da Super Finance — intermediadora de pagamentos Pix. Cobre Cash In (cobranças / QR Codes), Cash Out (transferências / contas), webhooks e contestações (MEDs).

Convenções da API:
- **Autenticação em dupla camada**: certificado mTLS (`.crt` + `.key` + senha do certificado) em toda requisição + Bearer Token OAuth (`grant_type=client_credentials`) no header `Authorization: Bearer {access_token}`.
- **Cash In e Cash Out são fluxos separados**: certificados diferentes, credenciais diferentes (`client_id` / `client_secret`) e tokens diferentes. Não reutilize o token de um fluxo no outro.
- **Expiração do token**: Cash In = `expires_in` 300 segundos; Cash Out = `expires_in` 3600 segundos. Renove o token antes do prazo (contado a partir da última renovação).
- **Base URL Cash In (API QR Codes)**: `https://api.pix.basspago.com.br`
- **Base URL Cash Out (API Contas)**: `https://pagamentos.basspago.com.br`
- **Credenciais**: geradas no painel FINANCE (`https://finance.superpagamentos.basspago.com.br`) — aba **API QRCODES** (Cash In) e aba **API CONTAS** (Cash Out).
- **IP allowlist (Cash Out)**: cadastre todos os IPs IPv4 dos servidores que efetuam saques. Requisições de IPs não cadastrados são bloqueadas.
- **Idempotência (Cash Out)**: transferências exigem header `x-idempotency-key` (chave única por transferência). Reenvio da mesma chave não processa de novo.
- **Valores Cash In (cobrança)**: `valor.original` é string em reais (ex.: `"49.90"`).
- **Valores Cash Out (transferência)**: `payment.amount` é number em reais (ex.: `150.00`); `payment.currency` sempre `"BRL"`.
- **Reembolso Cash In**: prazo máximo de 90 dias após o pagamento. Path usa `e2eid` da transação paga + `id` único gerado por você (único por E2E). `natureza`: `ORIGINAL` (devolução padrão) ou `RETIRADA` (Pix Saque/Troco).
- **Contestações (MEDs)**: responda em até 24 horas quando aguardando ação. Fluxo típico: `WAITING_PSP` → `DEFENDED` (após defesa) ou `CLOSED` (encerrada).
- **Webhooks**: enviados via POST para URLs cadastradas no FINANCE (aba WEBHOOKS). Tipos: Transferências, Recebimento, Estorno, Fila de saída, Infrações. Handler deve ser idempotente.
- **Comprovante PDF**: `data.pdf` vem em string base64; descompacte/decode para obter o arquivo.
- **Documentação**: `https://docs-finance.superpagamentos.com`

## Guias de implementação

- [Comece por aqui](https://docs-finance.superpagamentos.com/boas-vindas): Setup inicial — app Super Finance, cadastro, certificados, login no FINANCE, geração de credenciais Cash In/Out, cadastro de IPs e webhooks.
- [Integrar com I.A](https://docs-finance.superpagamentos.com/integrar-com-ia): Como apontar LLMs/agentes para este `llms.txt` e acelerar a integração.
- [Autenticação](https://docs-finance.superpagamentos.com/autenticacao): Como funcionam certificados, Bearer Token, bases URL e renovação de token.
- [Gere sua primeira transação](https://docs-finance.superpagamentos.com/primeira-transacao): Fluxo Cash In completo — criar cobrança Pix, parâmetros do body e webhooks de recebimento/reembolso/contestação.
- [Realize sua primeira transferência](https://docs-finance.superpagamentos.com/primeira-transferencia): Fluxo Cash Out completo — transferir por chave Pix, formatos de chave, `x-idempotency-key` e webhooks de transferência.
- [Webhooks](https://docs-finance.superpagamentos.com/webhooks): Como configurar URLs, e-mail de erro, pausa, método POST, headers extras e reenvio no painel FINANCE.

## Transações — Cash In (API QR Codes)

Base: `https://api.pix.basspago.com.br`. Use certificado + Bearer Token de Cash In.

- [Eventos de webhooks (Cash In)](https://docs-finance.superpagamentos.com/api-reference/eventos-webhooks): Payloads de `RECEIVE` (transação paga), `REFUND` (reembolso) e `INFRACTION` (contestação/MED), com tabela de campos.
- [POST /oauth/token — Autenticar conta](https://docs-finance.superpagamentos.com/api-reference/autenticar-conta): Gera Bearer Token Cash In. Body: `grant_type=client_credentials`, `client_id`, `client_secret` (credenciais da aba API QRCODES). Resposta: `access_token`, `token_type=Bearer`, `expires_in=300`.
- [POST /cob — Gerar transação PIX](https://docs-finance.superpagamentos.com/api-reference/gerar-transacao-pix): Cria cobrança. Body: `calendario.expiracao` (obrigatório), `valor.original` (obrigatório), `chave` (obrigatório), `devedor.cpf`/`devedor.nome` (opcionais), `solicitacaoPagador`, `infoAdicionais`. Retorna `txid`, `status=ATIVA`, `pixCopiaECola`, `location`.
- [GET /cob — Listar transações](https://docs-finance.superpagamentos.com/api-reference/listar-transacoes): Query obrigatória `inicio` e `fim` (RFC 3339). Opcionais: `cpf`, `cnpj`, `status` (`ATIVA`, `CONCLUIDA`, `REMOVIDA_PELO_USUARIO_RECEBEDOR`, `REMOVIDA_PELO_PSP`), `paginacao.paginaAtual` (default 0), `paginacao.itensPorPagina` (1–1000, default 100). Resposta: `parametros` + `cobs[]`.
- [GET /cob/{txid} — Consultar transação](https://docs-finance.superpagamentos.com/api-reference/consultar-transacao): Detalhe da cobrança por `txid`, incluindo array `pix[]` quando paga (`endToEndId`, `valor`, `horario`, `infoPagador`).
- [PUT /pix/{e2eid}/devolucao/{id} — Solicitar reembolso](https://docs-finance.superpagamentos.com/api-reference/solicitar-reembolso): Devolução total ou parcial. Path: `e2eid` da transação paga + `id` único por E2E. Body: `valor` (obrigatório), `natureza` (`ORIGINAL` ou `RETIRADA`), `descricao`. Prazo máximo: 90 dias.
- [GET /pix/{e2eid}/devolucao/{id} — Consultar reembolso](https://docs-finance.superpagamentos.com/api-reference/consultar-reembolso): Status da devolução (`EM_PROCESSAMENTO`, `DEVOLVIDO`, `NAO_REALIZADO`), `rtrId`, `horario.solicitacao` / `horario.liquidacao`.

## Transferências — Cash Out (API Contas)

Base: `https://pagamentos.basspago.com.br`. Use certificado + Bearer Token de Cash Out. Header `x-idempotency-key` obrigatório nas transferências.

- [Eventos de webhooks (Cash Out)](https://docs-finance.superpagamentos.com/api-reference/eventos-webhooks-cashout): Payloads de `TRANSFER` (transferência realizada / `LIQUIDATED`) e `CASHOUT` (rejeitada / `REJECTED` + `errorMessage`).
- [POST /oauth/token — Autenticar conta](https://docs-finance.superpagamentos.com/api-reference/autenticar-conta-cashout): Gera Bearer Token Cash Out. Credenciais da aba API CONTAS. Resposta: `expires_in=3600`.
- [POST /api/v2/pix/payments/dict — Transferir para chave](https://docs-finance.superpagamentos.com/api-reference/solicitar-transferencia): Transfere para chave Pix. Body: `payment.currency` + `payment.amount` (obrigatórios), `pixKey` (obrigatório), `priority` (`HIGH`|`NORM`, default `NORM`), `paymentFlow` (`INSTANT`|`APPROVAL_REQUIRED`, default `INSTANT`), `expiration` (1–10800, só com `NORM`, default 600), `description`, `creditorDocument` (obrigatório se `priority=HIGH`). Formatos de chave: CPF/CNPJ só números; telefone `+55DDDNUMERO`; e-mail; EVP (UUID).
- [POST /api/v2/pix/payments/qrc — Transferir para QR Code](https://docs-finance.superpagamentos.com/api-reference/transferir-qrcode): Mesma lógica da transferência por chave, mas com `qrCode` (Pix copia e cola) no lugar de `pixKey`.
- [GET /api/v2/accounts/balances — Consultar saldo](https://docs-finance.superpagamentos.com/api-reference/consultar-saldo): Query obrigatória `event_date_start` e `event_date_end` (ISO 8601). Opcionais: `page_offset` (min 1), `page_limit` (1–100, default 10), `sort_by=EVENT_DATE`, `sort_type` (`ASC`|`DESC`), `cut_edge_type` (`BEGIN_OF_DAY`|`END_OF_DAY`). Resposta: `data[].eventDate` + `balanceAmount` (`available`, `blocked`, `overdraft`).
- [GET /api/v2/pix/payments/idempotencyKey/{idempotencyKey} — Consultar transferência](https://docs-finance.superpagamentos.com/api-reference/consultar-transferencia): Busca transferência pela chave de idempotência. Retorna `status` (`PROCESSING`, `SETTLED`, `REJECTED`), `endToEndId`, `settledAt`, etc.
- [GET /api/v2/pix/payments/receipt/{e2eid} — Comprovante PIX (PDF)](https://docs-finance.superpagamentos.com/api-reference/comprovante-pix): Retorna `{ data: { pdf: "<base64>" } }`. Decode o base64 para obter o PDF.

## Contestações (MEDs)

Base Cash Out: `https://pagamentos.basspago.com.br`. Use certificado + Bearer Token de Cash Out.

- [GET /api/v2/infractions — Listar contestações](https://docs-finance.superpagamentos.com/api-reference/listar-contestacoes): Query obrigatória `last_change_start` e `last_change_end` (ISO 8601). Opcionais: `page_offset`, `page_limit` (1–100, default 10), `sort_by` (`EVENT_DATE`|`STATUS`), `status` (`ALL`, `ACKNOWLEDGED`, `WAITING_ADJUSTMENTS`, `DEFENDED`, `CLOSED`).
- [GET /api/v2/infractions/{infractionId} — Consultar infração](https://docs-finance.superpagamentos.com/api-reference/consultar-infracao): Detalhe da MED, incluindo `debtor`, `creditor`, `deadline`, `defenseSubmittedAt`, `closedAt`.
- [POST /api/v2/infractions/{infractionId}/defense — Enviar defesa](https://docs-finance.superpagamentos.com/api-reference/enviar-defesa): `multipart/form-data` com `defense` (texto obrigatório) e `files` (anexos opcionais: PDF/imagens). Resposta típica: `status=DEFENDED`, `filesCount`, `defenseSubmittedAt`.

## Recursos externos

- [Dashboard FINANCE](https://finance.superpagamentos.basspago.com.br): Login, credenciais, IPs permitidos e configuração de webhooks.
- [Configurações / WEBHOOKS](https://finance.superpagamentos.basspago.com.br/settings?tab=WEBHOOKS): Cadastro das URLs de evento.
- [App Store — Super Finance](https://apps.apple.com/br/app/super-finance/id6784259684): Cadastro da conta (iOS).
- [Google Play — Super Finance](https://play.google.com/store/apps/details?id=finance.onz.superfinance): Cadastro da conta (Android).
- [WhatsApp de suporte](https://api.whatsapp.com/send/?phone=%2B5511936217470&text=Ola%2C+estou+integrando+a+Super+Finance+em+meu+sistema+e+estou+com+duvidas%2C+poderia+me+auxiliar%3F&type=phone_number&app_absent=0): Canal de suporte à integração.
- [Este arquivo (llms.txt)](https://docs-finance.superpagamentos.com/llms.txt): Índice canônico para LLMs e agentes.