Conceptos

Conceptos fundamentales para integrar con la API de Owem Pay.

Modelo de Autenticacion

La API utiliza autenticacion en dos niveles:

Componente	Descripcion	Uso
Bearer Token	JWT generado via /api/v2/external/auth-token	Encabezado Authorization: Bearer {token} en todas las solicitudes
HMAC-SHA512	Firma del body de la solicitud	Encabezado hmac en solicitudes transaccionales (POST)

Flujo de Autenticacion

1. Envie client_id y client_secret al endpoint auth-token
2. Reciba el access_token (valido por 60 minutos)
3. Incluya el token en todas las solicitudes: Authorization: Bearer {access_token}
4. Para solicitudes POST, calcule el HMAC-SHA512 del body y envielo en el encabezado hmac

Detalles completos: Autenticacion | HMAC-SHA512

Valores Monetarios

Todos los valores se representan como enteros en centavos. Nunca utilice punto flotante.

Valor	Representacion	Campo JSON
R$ 1,00	100	"amount": 100
R$ 150,50	15050	"amount": 15050
R$ 1.000,00	100000	"amount": 100000
R$ 10.000,00	1000000	"amount": 1000000

Conversion

Para convertir centavos a reales: divida entre 100. Para convertir reales a centavos: multiplique por 100 y redondee.

Estado de Transaccion

Estado	Descripcion
pending	Esperando pago o aprobacion
processing	Transaccion en procesamiento en el SPI
completed	Transaccion completada con exito
settled	Liquidacion confirmada por el BACEN
failed	Transaccion fallida
refunded	Transaccion devuelta (total o parcialmente)
cancelled	Transaccion cancelada o expirada

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 es generado automaticamente por Owem Pay y se retorna 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	Correo electronico valido	contacto@empresa.com.br	5	20
phone	+55 + codigo de area + 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.