Visao Geral da API

A API Owem Pay permite integrar pagamentos PIX ao seu sistema. Todas as operacoes sao autenticadas via API Key + HMAC-SHA512 com IP Whitelist obrigatoria.

URL Base

Ambiente	URL
Producao	https://api.owem.com.br
Homologacao	https://api-hml.owem.com.br

Autenticacao

Tres camadas de seguranca independentes:

1. IP Whitelist -- IP de origem deve estar na whitelist configurada na API Key
2. API Key -- Header Authorization: ApiKey {client_id}:{client_secret} em todas as requisicoes
3. HMAC-SHA512 -- Assinatura do body da requisicao (obrigatorio para endpoints POST)

Veja Autenticacao e HMAC-SHA512 para detalhes.

Formato

Campo	Formato
Content-Type	application/json
Valores de entrada (request)	Inteiros em centavos (R$ 30,00 = 3000)
Valores de resposta	Inteiros em unidades base (R$ 30,00 = 300000, ÷ 10.000 para reais)
Datas	ISO 8601 (2026-03-09T15:30:00Z)
IDs	UUID v4 ou string alfanumerica
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq}

Conversao de valores

Para enviar: multiplique reais por 100. R$ 30,00 = 3000. Para ler respostas: divida por 10.000. 300000 ÷ 10.000 = R$ 30,00. Nunca use ponto flutuante -- sempre inteiros.

Padrao de Resposta

Sucesso

{
  "worked": true,
  "transaction_id": "PIXOUT20260309abcdef123456",
  "status": "processing"
}

Erro

{
  "worked": false,
  "detail": "Saldo insuficiente"
}

Codigos HTTP

Codigo	Significado
200	Sucesso
201	Recurso criado (webhook)
400	Parametros invalidos
401	API Key ausente ou invalida / HMAC invalido
403	IP nao autorizado na whitelist
404	Recurso nao encontrado
422	Validacao falhou (saldo insuficiente, chave invalida)
429	Rate limit excedido
500	Erro interno

Rate Limiting

Tipo	Limite
Por IP (autenticado)	60.000 requisicoes/minuto
Por IP (sem autenticacao)	5 requisicoes/minuto

Headers de resposta:

X-RateLimit-Remaining: 59997
Retry-After: 3  (apenas quando 429)

Idempotencia

Requisicoes POST aceitam o header Idempotency-Key para evitar processamento duplicado. O resultado e cacheado por 24 horas. Se a mesma chave for reenviada, a API retorna a resposta original com o header X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

External ID

Campo opcional external_id (max 128 chars, alfanumerico + ._:-) aceito em cash-in e cash-out. Retornado em respostas e webhooks. Permite consulta por referencia:

GET /api/external/transactions/ref/{external_id}

Veja Conceitos para detalhes.

Endpoints

PIX Cash Out (Envio)

Metodo	Endpoint	Descricao
POST	/api/external/pix/cash-out	Enviar PIX por chave ou copia-e-cola
POST	/api/external/pix/cash-out/approve	Aprovar cash-out pendente

PIX Cash In (Recebimento)

Metodo	Endpoint	Descricao
POST	/api/external/pix/cash-in	Gerar QR Code para recebimento

Consultas

Metodo	Endpoint	Descricao
GET	/api/external/transactions	Listar transacoes
GET	/api/external/transactions/:id	Consultar transacao por ID
GET	/api/external/transactions/e2e/:e2e_id	Consultar por E2E ID
GET	/api/external/transactions/tag/:tag	Consultar por tag (prefixo)
GET	/api/external/transactions/ref/:external_id	Consultar por external_id
GET	/api/external/transactions/:id/receipt	Comprovante

Conta

Metodo	Endpoint	Descricao
GET	/api/external/balance	Saldo da conta
GET	/api/external/statement	Extrato

Chaves PIX

Metodo	Endpoint	Descricao
GET	/api/external/pix/keys	Listar chaves PIX da conta

Devolucao

Metodo	Endpoint	Descricao
POST	/api/external/pix/refund	Devolucao PIX (total ou parcial)

MED

Metodo	Endpoint	Descricao
GET	/api/external/med	Listar MEDs
GET	/api/external/med/:id	Detalhes de um MED

Validacao

Metodo	Endpoint	Descricao
POST	/api/external/cpf/validate	Validar CPF

Webhooks

Metodo	Endpoint	Descricao
GET	/api/external/webhooks	Listar webhooks
POST	/api/external/webhooks	Cadastrar webhook
DELETE	/api/external/webhooks/:id	Remover webhook