Descripcion General de la API
La API Owem Pay permite integrar pagos PIX a su sistema. Todas las operaciones se autentican mediante API Key + HMAC-SHA512.
URL Base
| Entorno | URL |
|---|---|
| Produccion | https://api.owem.com.br |
Autenticacion
Todas las solicitudes requieren:
- Auth Token -- JWT obtenido via
POST /api/v2/external/auth-token - HMAC-SHA512 -- Firma del body de la solicitud (obligatorio para endpoints transaccionales)
Consulte Auth Token y HMAC-SHA512 para mas detalles.
Formato
| Campo | Formato |
|---|---|
| Content-Type | application/json |
| Valores monetarios | Entero en centavos (R$ 100,00 = 10000) |
| Fechas | ISO 8601 (2026-03-09T15:30:00Z) |
| IDs | UUID v4 o cadena alfanumerica |
| E2E ID | E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq} |
Patron de Respuesta
Exito
json
{
"worked": true,
"transaction_id": "PIXOUT20260309abcdef123456",
"status": "processing"
}Error
json
{
"worked": false,
"detail": "Saldo insuficiente"
}Codigos HTTP
| Codigo | Significado |
|---|---|
| 200 | Exito |
| 400 | Parametros invalidos |
| 401 | Token ausente o expirado |
| 403 | HMAC invalido |
| 404 | Recurso no encontrado |
| 422 | Validacion fallida (saldo insuficiente, clave invalida) |
| 429 | Limite de solicitudes excedido |
| 500 | Error interno |
Limite de Solicitudes
| Tipo | Limite |
|---|---|
| Por API Key | 120 solicitudes/minuto |
| Por IP | 5 solicitudes/minuto (sin autenticacion) |
Encabezados de respuesta:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1709990520Idempotencia
Las solicitudes de escritura (POST) aceptan el encabezado Idempotency-Key para evitar procesamiento duplicado. El resultado se almacena en cache durante 24 horas.
Idempotency-Key: unique-request-id-123Endpoints
| Metodo | Endpoint | Descripcion |
|---|---|---|
| POST | /api/v2/external/auth-token | Generar token JWT |
| POST | /api/v2/external/pix/cash-out | Enviar PIX |
| POST | /api/v2/external/pix/cash-out/approve | Aprobar cash-out pendiente |
| POST | /api/v2/external/pix/cash-in | Generar codigo QR para recepcion |
| GET | /api/v2/external/transactions | Listar transacciones |
| GET | /api/v2/external/transactions/:id | Consultar transaccion 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 | Comprobante |
| GET | /api/v2/external/balance | Saldo de la cuenta |
| GET | /api/v2/external/statement | Estado de cuenta |
| GET | /api/v2/external/pix/keys | Listar claves PIX |
| POST | /api/v2/external/pix/refund | Devolucion PIX |
| GET | /api/v2/external/med | Listar MEDs |
| GET | /api/v2/external/med/:id | Detalles MED |
| POST | /api/v2/external/cpf/validate | Validar CPF |
| GET | /api/v2/external/webhooks | Listar webhooks |
| POST | /api/v2/external/webhooks | Registrar webhook |
| DELETE | /api/v2/external/webhooks/:id | Eliminar webhook |