# Omnicash

> Gateway de pagamentos PIX brasileiro com API REST simples. Aceite cobranças PIX, processe saques (PIX-out), gerencie webhooks e saldo de vendedores via uma única integração.

Omnicash é uma plataforma BaaS (Banking-as-a-Service) que abstrai integração com adquirentes brasileiras (Nebula, Medusa, Evollute, SafePayments). Oferece dashboard administrativo, painel para vendedores, KYC, sistema de comissões/split, e SDKs em Node.js.

## Documentação principal

- [Documentação da API](https://omnicash.com.br/docs): guia completo da API REST, autenticação, transações, webhooks, saldo, idempotência e tratamento de erros (português).
- [API Reference (OpenAPI)](https://omnicash.com.br/api-docs): especificação OpenAPI/Swagger interativa de todos os endpoints.

## Quickstart

- [Quickstart — primeiro PIX em 5 minutos](https://omnicash.com.br/docs#quickstart): tutorial passo a passo desde a criação da chave de API até o recebimento do webhook de pagamento.

## Recursos da API

- [Autenticação](https://omnicash.com.br/docs#autenticacao): Bearer token, scopes de chave de API, separação test/live (sk_test_* vs sk_live_*).
- [Transações](https://omnicash.com.br/docs#transacoes): criar cobrança PIX, listar, consultar status, simular pagamentos no modo teste.
- [Webhooks](https://omnicash.com.br/docs#webhooks): eventos payment.succeeded/failed/expired, assinatura HMAC via header X-Omnicash-Signature, retry automático em 5xx.
- [Saldo](https://omnicash.com.br/docs#saldo): consultar saldo disponível e bloqueado por vendedor.
- [Clientes](https://omnicash.com.br/docs#clientes): cadastro e gerenciamento de clientes finais.

## Referência técnica

- [Idempotência](https://omnicash.com.br/docs#idempotencia): uso do header Idempotency-Key para garantir que retries não dupliquem cobranças.
- [Erros](https://omnicash.com.br/docs#erros): códigos de erro padronizados, formato JSON da resposta de erro, status HTTP usados.
- [Rate Limiting](https://omnicash.com.br/docs#rate-limiting): limites por chave de API, headers X-RateLimit-*, política de backoff recomendada.
- [SDKs](https://omnicash.com.br/docs#sdks): SDK oficial em Node.js/TypeScript (`npm install omnicash`).

## Endpoints principais

- [POST /api/v1/transactions](https://omnicash.com.br/api/v1/transactions): criar cobrança PIX.
- [GET /api/v1/transactions](https://omnicash.com.br/api/v1/transactions): listar transações.
- [GET /api/v1/transactions/:id](https://omnicash.com.br/docs#transacoes): consultar uma transação por ID.
- [GET /api/v1/balance](https://omnicash.com.br/api/v1/balance): consultar saldo disponível e bloqueado.
- [POST /api/v1/payouts](https://omnicash.com.br/docs#payouts): solicitar saque (PIX-out automático quando adquirente ativa suporta).
- [POST /api/v1/customers](https://omnicash.com.br/api/v1/customers): criar cliente final.

## Convenções

- Valores monetários na criação: centavos (inteiros). Em respostas de listagem/saldo: reais decimais.
- Datas: ISO 8601 UTC.
- Autenticação: header `Authorization: Bearer sk_live_...` ou `Authorization: Bearer sk_test_...`.
- Content-Type: `application/json`.
- Idempotência: header `Idempotency-Key` em POSTs sensíveis.

## Optional

- [Termos de uso](https://omnicash.com.br/termos)
- [Política de privacidade](https://omnicash.com.br/privacidade)
- [Cadastro](https://omnicash.com.br/signup)