Vision General de la API

La API Owem Pay permite integrar pagos PIX a su sistema. Todas las operaciones exigen API Key e IP Whitelist; endpoints POST agregan HMAC-SHA512 sobre el body.

URL Base

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

Autenticacion

Capas de seguridad (por tipo de solicitud):

1. IP Whitelist (todas) -- IP de origen debe estar en la whitelist configurada en la API Key
2. API Key (todas) -- Header Authorization: ApiKey {client_id}:{client_secret} en todas las solicitudes
3. HMAC-SHA512 (solo POST) -- Firma del body de la solicitud; obligatorio en POST /pix/cash-in, POST /pix/cash-out, POST /cpf/validate, POST /webhooks, POST /pix/refund. Solicitudes GET y DELETE no cargan HMAC (no poseen body a firmar).

Orden alfabetico obligatorio en el body HMAC

Requests POST que exigen HMAC deben firmar el body con claves en orden alfabetico. El backend hace Jason.decode + Jason.encode! en el body para validacion, lo que reordena las claves. Si su cliente no alfabetiza antes de firmar, el HMAC computado localmente no coincide con el del servidor → HTTP 401.

Detalles completos: HMAC-SHA512.

Vea Autenticacion y HMAC-SHA512 para detalles.

Formato

Campo	Formato
Content-Type	application/json
Valores de entrada (request)	Enteros en centavos (R$ 1,00 = 100)
Valores de respuesta	Enteros en subcentavos (unidades base; R$ 1,00 = 10000, ÷ 10.000 para reales)
Fechas	ISO 8601 en UTC con sufijo Z (2026-03-09T15:30:00Z)
IDs	UUID v4 o string alfanumerica
E2E ID	^E\d{8}[a-zA-Z0-9]{22,26}$ (estandar BACEN, 31-35 chars, sufijo puede contener letras)

Terminologia

En esta documentacion, subcentavos y unidades base se refieren a la misma unidad (10.000 = R$ 1,00). El termino "unidades base" aparece en algunos ejemplos heredados; considerelo sinonimo de subcentavos. Siempre divida el valor de la respuesta por 10.000 para obtener reales.

E2E puede contener letras

El sufijo despues de E + ISPB + timestamp es alfanumerico de 9 a 13 caracteres (no solo digitos). Bancos como Nubank emiten E2Es con letras al final. Siempre valide con la regex completa. Detalles en PIX Cash-In por E2E ID.

Conversion de valores

Para enviar: multiplique reales por 100. R$ 1,00 = 100. Para leer respuestas: divida por 10.000. 10000 ÷ 10.000 = R$ 1,00. Nunca use punto flotante -- siempre enteros.

Case de las claves (camelCase opcional)

Respuestas JSON usan snake_case por default (ej: transaction_id, end_to_end_id). Si su cliente prefiere camelCase, envie el header:

X-Key-Case: camelCase

El backend convierte todas las claves del JSON de respuesta (incluyendo objetos anidados) automaticamente. Ejemplo: transaction_id → transactionId, pix_key_type → pixKeyType. El header no afecta el body de entrada — envie siempre en snake_case al hacer POST.

Patron de Respuesta

Exito

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

Error

El formato del error varia segun la capa que rechazo la solicitud:

// Plug HMAC (401 firma invalida)
{ "worked": false, "detail": "Invalid HMAC signature" }

// ApiKeyAuth (401 / 403)
{ "error": { "status": 401, "message": "Invalid API key" } }

// FallbackController (404 / 400 / 409 / 422 / 500 — casos de negocio)
{ "errors": { "not_found": "transaction not found" } }

Vea la tabla completa en Autenticacion -- Respuestas de Error.

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)	90.000 solicitudes/minuto (1.500 req/s)
Por IP (autenticacion / login)	5 solicitudes/minuto
GET /balance	sin rate limit (polling alta frecuencia permitido)

Headers de respuesta:

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

Idempotencia

Solicitudes POST aceptan el header Idempotency-Key (max 256 caracteres) para evitar procesamiento duplicado. Solo respuestas 2xx (exito) son cacheadas por 24 horas. Si la misma clave es reenviada para el mismo metodo y endpoint, la API retorna la respuesta original con el header X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

Alcance de la clave

La clave esta vinculada a metodo + path + Idempotency-Key. La misma clave puede ser reutilizada en endpoints diferentes sin colisionar. Respuestas de error (4xx/5xx) no son cacheadas -- el cliente puede reintentar despues de corregir la falla.

GET/DELETE y Idempotency-Key

Solicitudes GET y DELETE ignoran silenciosamente el header Idempotency-Key -- el plug solo actua en POST. Enviar la clave en esos metodos no causa error, pero no genera cache ni replay.

Politicas de retry y cuarentena

• Cuarentena (stage=5): PIX Cash-Out preso en status: "processing" por mas de 30 minutos es movido a cuarentena, donde permanece aguardando resolucion manual por el equipo Owem. El status continua "processing" desde la perspectiva del cliente hasta la finalizacion. Detalles en el flujo: PIX Lifecycle.
• Retry automatico de webhooks: deliveries con falla (timeout, 5xx, conexion cerrada) son reagendadas en hasta 7 intentos (intervalos [0, 30s, 2min, 10min, 30min, 1h, 2h, 4h]). Vea Webhooks.
• Retry del cliente: al recibir 429, respete Retry-After. Al recibir 500 o timeout, use backoff exponencial + Idempotency-Key para evitar duplicacion. Vea Autenticacion para detalles.
• Ventana anti-replay del webhook: el header X-Owem-Timestamp es Unix time en segundos. El servidor no rechaza webhooks antiguos; cabe a su endpoint descartar entregas con |now - timestamp| > 300s (± 5 minutos) como defense-in-depth contra replay. Vea Webhooks -- Validando la Firma.

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 Consultar por External ID para detalles.

Endpoints

PIX Cash-Out (Envio)

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

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	Remover webhook