Conceitos

Conceitos fundamentais para integrar com a API da Owem Pay.

Modelo de Autenticacao

A API utiliza autenticacao em dois niveis:

Componente	Descricao	Uso
Bearer Token	JWT gerado via /api/v2/external/auth-token	Header Authorization: Bearer {token} em todas as requisicoes
HMAC-SHA512	Assinatura do body da requisicao	Header hmac em requisicoes transacionais (POST)

Fluxo de Autenticacao

1. Envie client_id e client_secret para o endpoint auth-token
2. Receba o access_token (valido por 60 minutos)
3. Inclua o token em todas as requisicoes: Authorization: Bearer {access_token}
4. Para requisicoes POST, calcule o HMAC-SHA512 do body e envie no header hmac

Detalhes completos: Autenticacao | HMAC-SHA512

Valores Monetarios

Todos os valores sao representados como inteiros em centavos. Nunca utilize ponto flutuante.

Valor	Representacao	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

Conversao

Para converter centavos para reais: divida por 100. Para converter reais para centavos: multiplique por 100 e arredonde.

Status de Transacao

Status	Descricao
pending	Aguardando pagamento ou aprovacao
processing	Transacao em processamento no SPI
completed	Transacao concluida com sucesso
settled	Liquidacao confirmada pelo BACEN
failed	Transacao falhou
refunded	Transacao devolvida (total ou parcialmente)
cancelled	Transacao cancelada ou expirada

End-to-End ID (E2E ID)

Identificador unico de uma transacao PIX no ecossistema do Banco Central. Formato padrao:

E{ISPB}{YYYYMMDDHHMM}{sequencial}

Exemplo: E37839059202603071530000001

Componente	Valor	Descricao
E	Prefixo fixo	Identifica como E2E ID
37839059	ISPB da Owem Pay	8 digitos
202603071530	Data e hora UTC	AAAAMMDDHHMM (12 digitos)
000001	Sequencial	6 digitos

O E2E ID e gerado automaticamente pela Owem Pay e retornado na resposta de cada operacao PIX. Use-o para rastrear transacoes entre instituicoes.

Tipos de Chave PIX

Tipo	Formato	Exemplo	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 (chave aleatoria)	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d	5	20

Padrao de Resposta

Todas as respostas da API seguem o padrao:

Sucesso

{
  "worked": true,
  ...
}

Erro

{
  "worked": false,
  "detail": "Descricao do erro"
}

O campo worked indica se a operacao foi bem-sucedida (true) ou falhou (false). Em caso de erro, o campo detail descreve o motivo.