Visão Geral da API
A API Owem Pay permite integrar pagamentos PIX ao seu sistema. Todas as operações são autenticadas via API Key + HMAC-SHA512.
URL Base
| Ambiente | URL |
|---|---|
| Produção | https://api.owem.com.br |
Autenticação
Todas as requisições exigem:
- Auth Token — JWT obtido via
POST /api/v2/external/auth-token - HMAC-SHA512 — Assinatura do body da requisição (obrigatório para endpoints transacionais)
Veja Auth Token e HMAC-SHA512 para detalhes.
Formato
| Campo | Formato |
|---|---|
| Content-Type | application/json |
| Valores monetários | Inteiro em centavos (R$ 100,00 = 10000) |
| Datas | ISO 8601 (2026-03-09T15:30:00Z) |
| IDs | UUID v4 ou string alfanumérica |
| E2E ID | E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq} |
Padrão de Resposta
Sucesso
json
{
"worked": true,
"transaction_id": "PIXOUT20260309abcdef123456",
"status": "processing"
}Erro
json
{
"worked": false,
"detail": "Saldo insuficiente"
}Códigos HTTP
| Código | Significado |
|---|---|
| 200 | Sucesso |
| 400 | Parâmetros inválidos |
| 401 | Token ausente ou expirado |
| 403 | HMAC inválido |
| 404 | Recurso não encontrado |
| 422 | Validação falhou (saldo insuficiente, chave inválida) |
| 429 | Rate limit excedido |
| 500 | Erro interno |
Rate Limiting
| Tipo | Limite |
|---|---|
| Por API Key | 120 requisições/minuto |
| Por IP | 5 requisições/minuto (sem autenticação) |
Headers de resposta:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1709990520Idempotência
Requisições de escrita (POST) aceitam o header Idempotency-Key para evitar processamento duplicado. O resultado é cacheado por 24 horas.
Idempotency-Key: unique-request-id-123Endpoints
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /api/v2/external/auth-token | Gerar token JWT |
| POST | /api/v2/external/pix/cash-out | Enviar PIX |
| POST | /api/v2/external/pix/cash-out/approve | Aprovar cash-out pendente |
| POST | /api/v2/external/pix/cash-in | Gerar QR Code para recebimento |
| GET | /api/v2/external/transactions | Listar transações |
| GET | /api/v2/external/transactions/:id | Consultar transação por ID |
| GET | /api/v2/external/transactions/e2e/:e2e_id | Consultar por E2E ID |
| GET | /api/v2/external/transactions/tag/:tag | Consultar por tag |
| GET | /api/v2/external/transactions/:id/receipt | Comprovante |
| GET | /api/v2/external/balance | Saldo da conta |
| GET | /api/v2/external/statement | Extrato |
| GET | /api/v2/external/pix/keys | Listar chaves PIX |
| POST | /api/v2/external/pix/refund | Devolução PIX |
| GET | /api/v2/external/med | Listar MEDs |
| GET | /api/v2/external/med/:id | Detalhes MED |
| POST | /api/v2/external/cpf/validate | Validar CPF |
| GET | /api/v2/external/webhooks | Listar webhooks |
| POST | /api/v2/external/webhooks | Cadastrar webhook |
| DELETE | /api/v2/external/webhooks/:id | Remover webhook |