Conceptos

Conceptos fundamentales para integrar con la API de Owem Pay.

Arquitectura de Seguridad

La API utiliza tres capas de proteccion independientes. Todas son obligatorias.

Capa 1 -- API Key + Secret

Cada integrador recibe un par de credenciales (client_id y client_secret). El secret nunca se almacena en texto plano -- guardamos solo el hash. Cuando llega una solicitud, el secret enviado se compara con el hash almacenado. Si no coincide, la solicitud se rechaza inmediatamente, antes de llegar a la logica de negocio.

Capa 2 -- Firma HMAC-SHA512 por Solicitud

Ademas de la API Key, cada solicitud transaccional (POST) necesita enviar una firma HMAC-SHA512 en el header hmac.

El proceso funciona asi:

1. El integrador serializa el body de la solicitud como JSON
2. Genera el hash HMAC-SHA512 usando el client_secret como clave
3. Envia el hash en hexadecimal en el header hmac

De nuestro lado, recalculamos el hash con el mismo metodo y lo comparamos con el valor recibido. Si cualquier byte del contenido fue alterado en el camino (por ejemplo, en un ataque man-in-the-middle), la firma no coincidira y la solicitud se rechaza con error 401. Esta comparacion se realiza en tiempo constante (constant-time comparison), lo que evita ataques de timing que intentan descubrir la firma byte a byte.

Capa 3 -- Whitelist de IP Obligatoria

Cada API Key solo puede usarse desde IPs previamente autorizados. Incluso si alguien tiene acceso a las credenciales, no podra usar la API desde otro IP. Las solicitudes desde IPs no autorizados reciben 403 Forbidden.

Protecciones Adicionales

Proteccion	Descripcion
Rate Limiting	60.000 solicitudes/minuto por IP. Endpoints sin autenticacion: 5 req/min
Cloud Armor (WAF)	Firewall de aplicacion protegiendo el cluster GKE
HTTPS obligatorio	TLS 1.2 o superior en todas las conexiones
HSTS	HTTP Strict Transport Security habilitado

Detalles completos: Autenticacion | HMAC-SHA512

Por que HMAC y no mTLS?

El mTLS (mutual TLS) agrega autenticacion via certificado X.509 a nivel de conexion. Es una capa valida, pero en nuestro escenario el HMAC por solicitud ofrece proteccion equivalente o mas adecuada:

Aspecto	mTLS	HMAC-SHA512
Que valida	La conexion (canal TLS)	Cada solicitud individualmente
Integridad del payload	No -- si la conexion es confiable, las solicitudes pasan	Si -- cualquier alteracion en el body rechaza la solicitud
Gestion operacional	Compleja: emision, rotacion, revocacion, CRL/OCSP	Simple: genera nuevo par, actualiza, invalida anterior
Incidentes comunes	Certificados expirados o mal gestionados	Raros -- la clave es un string, sin ciclo de vida complejo

El TLS ya garantiza cifrado del transporte. El HMAC entra como capa adicional, garantizando integridad y autenticidad del payload -- algo que el mTLS por si solo no cubre.

Valores Monetarios

La API Owem Pay usa dos unidades diferentes dependiendo de la direccion:

Direccion	Unidad	Escala	Ejemplo R$ 30,00
Solicitud enviada (request body)	centavos	BRL x 100	3000
Respuesta recibida (response body)	unidades base	BRL x 10.000	300000

Conversion rapida

• Para enviar: multiplique el valor en 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

Tabla de referencia

Valor BRL	Request (centavos)	Response (unidades base)
R$ 1,00	100	10000
R$ 30,00	3000	300000
R$ 150,50	15050	1505000
R$ 1.000,00	100000	10000000

Atencion

El valor 3000 en la solicitud (R$ 30,00) se convierte en 300000 en la respuesta. Son el mismo valor en BRL, representado en unidades diferentes. Si divide la respuesta por 100 en vez de 10.000, obtendra R$ 3.000,00 en vez de R$ 30,00.

External ID

El campo external_id es un identificador opcional que usted define en su sistema para rastrear transacciones. Se acepta en los endpoints de cash-in y cash-out y se devuelve en todas las respuestas y webhooks asociados.

Atributo	Valor
Obligatorio	No
Tamano maximo	128 caracteres
Caracteres permitidos	Alfanumericos, ., _, :, -
Regex	^[a-zA-Z0-9._:\-]+$
Ejemplo	"order-9876", "invoice-4521", "ref:2026-03-07:001"

Ademas de devolverse en las respuestas, puede consultar una transaccion por el external_id:

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

Rastreo

Use el external_id para correlacionar transacciones de Owem Pay con pedidos, facturas o registros de su sistema. Los valores duplicados no se rechazan, pero recomendamos unicidad para facilitar la conciliacion.

Idempotencia

Las solicitudes de escritura (POST) aceptan el header Idempotency-Key para evitar procesamiento duplicado. Si la misma clave se envia en una segunda solicitud identica dentro de 24 horas, la API retorna la respuesta original cacheada en vez de procesar nuevamente.

Idempotency-Key: unique-request-id-123

Atributo	Valor
Header	Idempotency-Key
Tamano maximo	256 caracteres
TTL del cache	24 horas
Se aplica a	Solo POST (cash-in, cash-out, refund, webhooks, CPF)
Respuesta replay	Header X-Idempotent-Replay: true

Importante

La clave de idempotencia considera metodo + path + clave. Dos solicitudes para endpoints diferentes con la misma clave se tratan como operaciones distintas.

Estado de Transaccion

Cash In (Cobros)

Estado	Descripcion
active	QR Code generado, esperando pago
pending	Pago detectado, en procesamiento
completed	Pago confirmado y acreditado en la cuenta
failed	Pago fallo
cancelled	QR Code expirado (24h) o cancelado

Cash Out (Envios)

Estado	Descripcion
pending_approval	Esperando aprobacion (flujo crear + aprobar)
processing	Enviado al SPI, esperando liquidacion
completed	Liquidado con exito
failed	Rechazado por el SPI o error en el procesamiento
refunded	Devuelto (total o parcialmente)

End-to-End ID (E2E ID)

Identificador unico de una transaccion PIX en el ecosistema del Banco Central. Formato estandar:

E{ISPB}{YYYYMMDDHHMM}{secuencial}

Ejemplo: E37839059202603071530000001

Componente	Valor	Descripcion
E	Prefijo fijo	Identifica como E2E ID
37839059	ISPB de Owem Pay	8 digitos
202603071530	Fecha y hora UTC	AAAAMMDDHHMI (12 digitos)
000001	Secuencial	6 digitos

El E2E ID se genera automaticamente por Owem Pay y se devuelve en la respuesta de cada operacion PIX. Uselo para rastrear transacciones entre instituciones.

Tipos de Clave PIX

Tipo	Formato	Ejemplo	Limite PF	Limite PJ
cpf	11 digitos	12345678901	1	--
cnpj	14 digitos	12345678000190	--	1
email	E-mail valido	contato@empresa.com.br	5	20
phone	+55 + DDD + numero	+5511999998888	5	20
evp	UUID v4 (clave aleatoria)	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d	5	20

Patron de Respuesta

Todas las respuestas de la API siguen el patron:

Exito

{
  "worked": true,
  ...
}

Error

{
  "worked": false,
  "detail": "Descripcion del error"
}

El campo worked indica si la operacion fue exitosa (true) o fallo (false). En caso de error, el campo detail describe el motivo.