Vision 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 con IP Whitelist obligatoria.

URL Base

Ambiente	URL
Produccion	https://api.owem.com.br
Homologacion	https://api-hml.owem.com.br

Autenticacion

Tres capas de seguridad independientes:

1. IP Whitelist -- La IP de origen debe estar en la whitelist configurada en la API Key
2. API Key -- Header Authorization: ApiKey {client_id}:{client_secret} en todas las solicitudes
3. HMAC-SHA512 -- Firma del body de la solicitud (obligatorio para endpoints POST)

Vea Autenticacion y HMAC-SHA512 para detalles.

Formato

Campo	Formato
Content-Type	application/json
Valores de entrada (request)	Enteros en centavos (R$ 30,00 = 3000)
Valores de respuesta	Enteros en unidades base (R$ 30,00 = 300000, / 10.000 para reales)
Fechas	ISO 8601 (2026-03-09T15:30:00Z)
IDs	UUID v4 o string alfanumerica
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq}

Conversion de valores

Para enviar: multiplique reales por 100. R$ 30,00 = 3000. Para leer respuestas: divida por 10.000. 300000 / 10.000 = R$ 30,00. Nunca use punto flotante -- siempre enteros.

Patron de Respuesta

Exito

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

Error

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

Codigos HTTP

Codigo	Significado
200	Exito
201	Recurso creado (webhook)
400	Parametros invalidos
401	API Key ausente o invalida / HMAC invalido
403	IP no autorizado en la whitelist
404	Recurso no encontrado
422	Validacion fallida (saldo insuficiente, clave invalida)
429	Rate limit excedido
500	Error interno

Rate Limiting

Tipo	Limite
Por IP (autenticado)	60.000 solicitudes/minuto
Por IP (sin autenticacion)	5 solicitudes/minuto

Headers de respuesta:

X-RateLimit-Remaining: 59997
Retry-After: 3  (solo cuando 429)

Idempotencia

Las solicitudes POST aceptan el header Idempotency-Key para evitar procesamiento duplicado. El resultado se almacena en cache durante 24 horas. Si la misma clave se reenvia, la API retorna la respuesta original con el header X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

External ID

Campo opcional external_id (max 128 chars, alfanumerico + ._:-) aceptado en cash-in y cash-out. Retornado en respuestas y webhooks. Permite consulta por referencia:

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

Vea Conceptos para detalles.

Endpoints

PIX Cash Out (Envio)

Metodo	Endpoint	Descripcion
POST	/api/external/pix/cash-out	Enviar PIX por clave o copia y pega
POST	/api/external/pix/cash-out/approve	Aprobar cash-out pendiente

PIX Cash In (Cobro)

Metodo	Endpoint	Descripcion
POST	/api/external/pix/cash-in	Generar QR Code para cobro

Consultas

Metodo	Endpoint	Descripcion
GET	/api/external/transactions	Listar transacciones
GET	/api/external/transactions/:id	Consultar transaccion por ID
GET	/api/external/transactions/e2e/:e2e_id	Consultar por E2E ID
GET	/api/external/transactions/tag/:tag	Consultar por tag (prefijo)
GET	/api/external/transactions/ref/:external_id	Consultar por external_id
GET	/api/external/transactions/:id/receipt	Comprobante

Cuenta

Metodo	Endpoint	Descripcion
GET	/api/external/balance	Saldo de la cuenta
GET	/api/external/statement	Extracto

Claves PIX

Metodo	Endpoint	Descripcion
GET	/api/external/pix/keys	Listar claves PIX de la cuenta

Devolucion

Metodo	Endpoint	Descripcion
POST	/api/external/pix/refund	Devolucion PIX (total o parcial)

MED

Metodo	Endpoint	Descripcion
GET	/api/external/med	Listar MEDs
GET	/api/external/med/:id	Detalles de un MED

Validacion

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

Webhooks

Metodo	Endpoint	Descripcion
GET	/api/external/webhooks	Listar webhooks
POST	/api/external/webhooks	Registrar webhook
DELETE	/api/external/webhooks/:id	Eliminar webhook