API v1

Documentação da API

A API Omnicash é organizada em torno de REST. Aceita corpos JSON, retorna respostas JSON e usa códigos de status HTTP padrão, autenticação via Bearer token e webhooks para eventos assíncronos.

URL Base

text

https://omnicash.com.br/api/v1

Convenções

Todas as requisições devem usar HTTPS. Corpos de requisição em JSON exigem o header Content-Type: application/json. Datas seguem ISO 8601. Valores monetários na criação são informados em centavos (inteiros); em respostas de listagem e saldo são retornados em reais decimais como string ou number.

Autenticação

Toda requisição requer autenticação via chave de API gerada no painel. Cada chave é criada com um conjunto de scopes que limitam o acesso.

Bearer Token

bash

curl https://omnicash.com.br/api/v1/transactions \
  -H "Authorization: Bearer sk_live_sua_chave"

Basic Auth

Alternativa: a chave como username em Basic Auth (senha vazia).

bash

curl https://omnicash.com.br/api/v1/transactions \
  -u "sk_live_sua_chave:"

Scopes

Scope

Permissões

transactions:read

Listar e consultar transações

transactions:write

Criar transações PIX

customers:read

Listar clientes

payouts:read

Consultar saldo e payouts

Nunca exponha a chave secreta no frontend ou em repositórios públicos. Todas as requisições devem ser feitas via HTTPS.

Transações

Transações representam cobranças PIX. Crie, liste ou consulte uma transação específica.

Criar transação

POST/v1/transactions

Body

customer.nameobrig.

string

Nome completo do cliente (mín. 2)

customer.emailobrig.

string

E-mail do cliente

customer.phoneobrig.

string

Telefone com DDD (ex: +5511999998888)

customer.cpfobrig.

string

CPF válido (com ou sem máscara)

amountobrig.

integer

Valor em centavos (mínimo 100)

paymentMethodobrig.

string

Atualmente apenas "pix"

items[].nameobrig.

string

Nome do item

items[].quantityobrig.

number

Quantidade (mínimo 1)

items[].unitPriceobrig.

number

Preço unitário em centavos

items[].isPhysical

boolean

Produto físico (default: false)

items[].externalRef

string

Referência externa do item

externalId

string

ID externo no seu sistema

postbackUrl

string

URL de webhook específica desta transação

pix.expiresInMinutes

integer

Expiração em minutos (5–43200)

pix.expiresInDays

integer

Expiração em dias (1–30, default 1)

ip

string

IP do pagador (antifraude)

Headers opcionais

Idempotency-Key

string

Chave única (máx. 255). Cache de 24h. Respostas replicadas vêm com Idempotent-Replayed: true

X-Async

boolean

Se "true", processa em background e retorna 202

Requisição

bash

curl -X POST https://omnicash.com.br/api/v1/transactions \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345" \
  -d '{
    "customer": {
      "name": "Maria Santos",
      "email": "maria@email.com",
      "phone": "+5511999998888",
      "cpf": "529.982.247-25"
    },
    "amount": 15900,
    "paymentMethod": "pix",
    "items": [
      { "name": "Plano Pro", "quantity": 1, "unitPrice": 15900 }
    ],
    "externalId": "pedido-12345"
  }'

Resposta — 200 OK

json

{
  "success": true,
  "data": {
    "id": 1234,
    "externalId": "evo_abc123",
    "amount": 15900,
    "status": "pending",
    "pix": {
      "qrcode": "00020126580014BR.GOV.BCB.PIX...",
      "qrcodeBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "expiresAt": "2026-04-09T17:00:00.000Z",
    "createdAt": "2026-04-08T17:00:00.000Z",
    "customer": {
      "id": 42,
      "name": "Maria Santos",
      "email": "maria@email.com"
    }
  }
}

Resposta — 202 Accepted (async)

json

{
  "success": true,
  "async": true,
  "data": {
    "id": 1234,
    "amount": 15900,
    "status": "pending",
    "createdAt": "2026-04-08T17:00:00.000Z",
    "customer": { "id": 42, "name": "Maria Santos", "email": "maria@email.com" }
  }
}

Listar transações

GET/v1/transactions

Query parameters

limit

integer

1–100 (default 20)

starting_after

string

Cursor: o nextCursor da página anterior

status

string

pending, processing, success, failed, refunded, expired, chargeback

date_from

string

Data inicial (ISO 8601)

date_to

string

Data final (ISO 8601)

min_amount

number

Valor mínimo em reais (decimal)

max_amount

number

Valor máximo em reais (decimal)

external_id

string

Filtra pelo externalId do gateway

bash

curl "https://omnicash.com.br/api/v1/transactions?limit=10&status=success" \
  -H "Authorization: Bearer sk_live_sua_chave"

json

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "amount": "159.00",
      "currency": "BRL",
      "status": "success",
      "method": "pix",
      "externalId": "evo_abc123",
      "customerName": "Maria Santos",
      "customerEmail": "maria@email.com",
      "gatewayProvider": "evollute",
      "createdAt": "2026-04-08T17:00:00.000Z",
      "expiresAt": "2026-04-09T17:00:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "1234"
  }
}

Diferente da criação (centavos), o campo amount retornado na listagem vem como string decimal em reais (ex: "159.00").

Consultar transação

GET/v1/transactions/:id

Sincroniza o status com o gateway em tempo real (quando suportado).

bash

curl https://omnicash.com.br/api/v1/transactions/1234 \
  -H "Authorization: Bearer sk_live_sua_chave"

json

{
  "success": true,
  "data": {
    "id": 1234,
    "externalId": "evo_abc123",
    "amount": "159.00",
    "currency": "BRL",
    "status": "success",
    "method": "pix",
    "paymentData": {
      "pix": { "qrcode": "00020126...", "qrcodeBase64": "iVBORw0..." }
    },
    "customerName": "Maria Santos",
    "customerEmail": "maria@email.com",
    "postbackUrl": null,
    "createdAt": "2026-04-08T17:00:00.000Z"
  }
}

Saldo

Consulte o saldo disponível, pendente e total. Os valores já consideram MDR, taxa fixa por transação e payouts realizados.

GET/v1/balance

bash

curl https://omnicash.com.br/api/v1/balance \
  -H "Authorization: Bearer sk_live_sua_chave"

json

{
  "success": true,
  "data": {
    "available": 1250.50,
    "pending": 340.00,
    "total": 1590.50,
    "currency": "BRL",
    "payoutFee": 3.50
  }
}

available é o saldo já liberado (líquido de taxas e payouts pagos/em processamento). pending reflete transações em pending/processing. payoutFee é a taxa por saque cobrada pela plataforma. Valores em reais decimais.

Clientes

Clientes são criados/atualizados automaticamente quando uma transação é processada (deduplicação por email).

GET/v1/customers

Query parameters

limit

integer

1–100 (default 20)

starting_after

string

Cursor de paginação

status

string

active ou inactive

email

string

Busca parcial por e-mail (case-insensitive)

name

string

Busca parcial por nome (case-insensitive)

bash

curl "https://omnicash.com.br/api/v1/customers?email=maria&limit=10" \
  -H "Authorization: Bearer sk_live_sua_chave"

json

{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "Maria Santos",
      "email": "maria@email.com",
      "status": "active",
      "country": "BR",
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "total": 340,
    "nextCursor": "42"
  }
}

Webhooks

Webhooks notificam seu servidor quando eventos acontecem. Configure URLs no painel (até 10 endpoints, cada um com sua própria seleção de eventos) ou use postbackUrl em uma transação específica.

Eventos

Evento

Quando dispara

payment.created

Nova cobrança PIX criada (status pending)

payment.succeeded

Pagamento confirmado pelo banco (status success)

payment.failed

Pagamento falhou ou QR Code expirou

refund.created

Reembolso processado (status refunded)

dispute.opened

MED ou chargeback aberto pelo pagador

Headers enviados

Content-Typeobrig.

string

application/json

X-Omnicash-Signatureobrig.

string

HMAC-SHA256 do body no formato sha256=<hex>

X-Omnicash-Timestampobrig.

string

Timestamp ISO 8601 do envio

User-Agentobrig.

string

Omnicash-Webhook/1.0

Payload

json

{
  "event": "payment.succeeded",
  "data": {
    "transactionId": 1234,
    "amount": "159.00",
    "currency": "BRL",
    "status": "success",
    "method": "pix",
    "customerName": "Maria Santos",
    "customerEmail": "maria@email.com",
    "paidAt": "2026-04-08T17:00:45.000Z",
    "createdAt": "2026-04-08T17:00:00.000Z"
  },
  "timestamp": "2026-04-08T17:00:46.000Z"
}

Verificando a assinatura

Use sempre o body raw (Buffer/string). Nunca JSON.stringify de objeto já parseado — a serialização pode diferir.

javascript

const crypto = require("crypto");

function verify(rawBody, sigHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(sigHeader),
    Buffer.from(expected)
  );
}

// Express — use express.raw() para preservar o body
app.post(
  "/webhooks/omnicash",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-omnicash-signature"];
    if (!verify(req.body, signature, process.env.WEBHOOK_SECRET)) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const event = JSON.parse(req.body);
    if (event.event === "payment.succeeded") {
      // Liberar produto/serviço usando event.data.transactionId
    }

    res.json({ received: true });
  }
);

Política de retry

Se seu endpoint não responder com 2xx em até 10 segundos, tentaremos novamente até 3 vezes (delays de 0s, 2s e 5s). URLs internas/loopback são bloqueadas por proteção SSRF.

Testar endpoint

POST/v1/webhooks/ping

Envia um evento test.ping para validar conectividade.

urlobrig.

string

URL HTTPS do endpoint a testar

bash

curl -X POST https://omnicash.com.br/api/v1/webhooks/ping \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seuservidor.com/webhooks" }'

Erros

A API retorna códigos HTTP padronizados e um corpo JSON com detalhes do erro. Existem dois formatos de envelope em uso — sempre confira o campo code (presente em ambos) para tratar o erro de forma consistente.

Formato 1 — Aninhado

Usado em autenticação, rate limit e erros de gateway.

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de requisições excedido. Tente novamente em breve."
  }
}

Formato 2 — Top-level

Usado em validação Zod e erros internos.

json

{
  "error": "Dados inválidos",
  "code": "VALIDATION_ERROR",
  "fields": {
    "amount": ["Number must be greater than or equal to 100"]
  }
}

Status HTTP

Status

Significado

200

Sucesso

201

Recurso criado

202

Aceito (processamento assíncrono)

400

Requisição inválida

401

Chave de API ausente ou inválida

403

Sem permissão (scope insuficiente ou conta suspensa)

404

Recurso não encontrado

422

Entidade não processável

429

Rate limit excedido

500

Erro interno do servidor

502

Falha de comunicação com o gateway

503

Recurso temporariamente indisponível

Códigos (campo error.code)

Code

Significado

VALIDATION_ERROR

Campos ausentes ou inválidos (vem com fields)

BAD_REQUEST

Parâmetro malformado

UNAUTHORIZED

Chave de API ausente ou inválida

FORBIDDEN

Scope insuficiente

ACCOUNT_SUSPENDED

Conta do merchant suspensa

NOT_FOUND

Recurso não existe ou pertence a outro merchant

INVALID_URL

URL informada é inacessível

CONNECTION_FAILED

Falha ao conectar com o endpoint

RATE_LIMITED

Limite de 120 req/min por chave excedido

GATEWAY_ERROR

Erro no provedor de pagamento (502)

MAINTENANCE_MODE

Plataforma em manutenção

SERVICE_UNAVAILABLE

Recurso temporariamente indisponível

SERVER_ERROR

Erro interno — tente novamente

Rate Limiting

A API limita requisições a 120 requisições por minuto por chave de API, em janela deslizante.

Headers de resposta

X-RateLimit-Limit

integer

Limite total por minuto (120)

X-RateLimit-Remaining

integer

Requisições restantes na janela atual

X-RateLimit-Reset

timestamp

Timestamp Unix de quando o limite reseta

Retry-After

integer

Segundos para aguardar (presente apenas no 429)

Resposta 429

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de requisições excedido. Tente novamente em breve."
  }
}

Para alto volume em criações de transação, envie X-Async: true e receba 202 Accepted imediatamente — a transação é processada em background e você recebe o resultado via webhook.