Conceitos

Conceitos fundamentais para integrar com a API da Owem Pay.

Arquitetura de Seguranca

A API utiliza tres camadas de protecao independentes. Todas sao obrigatorias.

Camada 1 -- API Key + Secret

Cada integrador recebe um par de credenciais (client_id e client_secret). O secret nunca e armazenado em texto puro -- guardamos apenas o hash. Quando uma requisicao chega, o secret enviado e comparado com o hash armazenado. Se nao corresponder, a requisicao e rejeitada imediatamente, antes de chegar a logica de negocio.

Camada 2 -- Assinatura HMAC-SHA512 por Requisicao

Alem da API Key, cada requisicao transacional (POST) precisa enviar uma assinatura HMAC-SHA512 no header hmac.

O processo funciona assim:

1. O integrador serializa o body da requisicao como JSON
2. Gera o hash HMAC-SHA512 usando o client_secret como chave
3. Envia o hash em hexadecimal no header hmac

Do nosso lado, recalculamos o hash com o mesmo metodo e comparamos com o valor recebido. Se qualquer byte do conteudo for alterado no caminho (por exemplo, em um ataque man-in-the-middle), a assinatura nao vai bater e a requisicao e rejeitada com erro 401. Essa comparacao e feita em tempo constante (constant-time comparison), o que evita ataques de timing que tentam descobrir a assinatura byte a byte.

Camada 3 -- Whitelist de IP Obrigatoria

Cada API Key so pode ser usada a partir de IPs previamente autorizados. Mesmo que alguem tenha acesso as credenciais, nao conseguira usar a API a partir de outro IP. Requisicoes de IPs nao autorizados recebem 403 Forbidden.

Protecoes Adicionais

Protecao	Descricao
Rate Limiting	60.000 requisicoes/minuto por IP. Endpoints sem autenticacao: 5 req/min
Cloud Armor (WAF)	Firewall de aplicacao protegendo o cluster GKE
HTTPS obrigatorio	TLS 1.2 ou superior em todas as conexoes
HSTS	HTTP Strict Transport Security habilitado

Detalhes completos: Autenticacao | HMAC-SHA512

Por que HMAC e nao mTLS?

O mTLS (mutual TLS) adiciona autenticacao via certificado X.509 no nivel da conexao. E uma camada valida, mas no nosso cenario o HMAC por requisicao oferece protecao equivalente ou mais adequada:

Aspecto	mTLS	HMAC-SHA512
O que valida	A conexao (canal TLS)	Cada requisicao individualmente
Integridade do payload	Nao -- se a conexao e confiavel, requisicoes passam	Sim -- qualquer alteracao no body rejeita a requisicao
Gestao operacional	Complexa: emissao, rotacao, revogacao, CRL/OCSP	Simples: gera novo par, atualiza, invalida anterior
Incidentes comuns	Certificados expirados ou mal gerenciados	Raros -- chave e string, sem ciclo de vida complexo

O TLS ja garante criptografia do transporte. O HMAC entra como camada adicional, garantindo integridade e autenticidade do payload -- algo que o mTLS por si so nao cobre.

Valores Monetarios

A API Owem Pay usa duas unidades diferentes dependendo da direcao:

Direcao	Unidade	Escala	Exemplo R$ 30,00
Requisicao enviada (request body)	centavos	BRL x 100	3000
Resposta recebida (response body)	unidades base	BRL x 10.000	300000

Conversao rapida

• Para enviar: multiplique o valor em reais por 100. R$ 30,00 = 3000
• Para ler respostas: divida por 10.000. 300000 / 10.000 = R$ 30,00
• Nunca use ponto flutuante -- sempre inteiros

Tabela 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

Atencao

O valor 3000 na requisicao (R$ 30,00) vira 300000 na resposta. Sao o mesmo valor em BRL, representado em unidades diferentes. Se voce dividir a resposta por 100 em vez de 10.000, obtera R$ 3.000,00 em vez de R$ 30,00.

External ID

O campo external_id e um identificador opcional que voce define no seu sistema para rastrear transacoes. Ele e aceito nos endpoints de cash-in e cash-out e devolvido em todas as respostas e webhooks associados.

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

Alem de ser retornado nas respostas, voce pode consultar uma transacao pelo external_id:

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

Rastreamento

Use o external_id para correlacionar transacoes da Owem Pay com pedidos, faturas ou registros do seu sistema. Valores duplicados nao sao rejeitados, mas recomendamos unicidade para facilitar a conciliacao.

Idempotencia

Requisicoes de escrita (POST) aceitam o header Idempotency-Key para evitar processamento duplicado. Se a mesma chave for enviada em uma segunda requisicao identica dentro de 24 horas, a API retorna a resposta original cacheada em vez de processar novamente.

Idempotency-Key: unique-request-id-123

Atributo	Valor
Header	Idempotency-Key
Tamanho maximo	256 caracteres
TTL do cache	24 horas
Aplica-se a	Apenas POST (cash-in, cash-out, refund, webhooks, CPF)
Resposta replay	Header X-Idempotent-Replay: true

Importante

A chave de idempotencia considera metodo + path + chave. Duas requisicoes para endpoints diferentes com a mesma chave sao tratadas como operacoes distintas.

Status de Transacao

Cash In (Recebimentos)

Status	Descricao
active	QR Code gerado, aguardando pagamento
pending	Pagamento detectado, em processamento
completed	Pagamento confirmado e creditado na conta
failed	Pagamento falhou
cancelled	QR Code expirado (24h) ou cancelado

Cash Out (Envios)

Status	Descricao
pending_approval	Aguardando aprovacao (fluxo criar + aprovar)
processing	Enviado ao SPI, aguardando liquidacao
completed	Liquidado com sucesso
failed	Rejeitado pelo SPI ou erro no processamento
refunded	Devolvido (total ou parcialmente)

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.