Primeiros Passos

Integre sua aplicacao com a API da Owem Pay e realize sua primeira operacao PIX em poucos minutos.

1. Obtenha suas credenciais

Solicite ao administrador da sua conta Owem Pay:

• Client ID -- identificador da sua API Key (prefixo cli_)
• Client Secret -- chave secreta para autenticacao e assinatura HMAC (prefixo sk_)

Seguranca

Nunca exponha o client_secret em codigo frontend ou repositorios publicos. Utilize variaveis de ambiente no seu servidor.

2. Configure a autenticacao

Todas as requisicoes exigem o header Authorization com suas credenciais API Key:

# Formato do header:
Authorization: ApiKey {client_id}:{client_secret}

A API Key e permanente -- nao expira. Nao e necessario gerar tokens.

3. Consulte o saldo

Teste a integracao consultando o saldo da conta:

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Resposta:

{
  "worked": true,
  "balance": 300000,
  "available": 300000,
  "pending": 0,
  "currency": "BRL"
}

Valores monetarios

Valores de entrada (request) sao em centavos: R$ 30,00 = 3000. Valores de resposta sao em unidades base: 300000 ÷ 10.000 = R$ 30,00. Nunca use ponto flutuante -- sempre inteiros.

4. Gere uma cobranca PIX (Cash-In)

Crie um QR Code para receber R$ 30,00:

BODY='{"amount":3000,"description":"Pedido #1234","external_id":"order-9876"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/pix/cash-in \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Resposta:

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}

Note que voce enviou 3000 (centavos) e recebeu 300000 (unidades base). Ambos representam R$ 30,00.

Exiba o qr_code_image ou o codigo copia-e-cola (qr_code) ao pagador.

5. Consulte o status

Acompanhe o pagamento consultando pelo transaction_id:

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Quando o pagamento for confirmado, o status muda para completed.

Voce tambem pode consultar pelo external_id:

curl -X GET https://api.owem.com.br/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

6. Receba notificacoes (Webhooks)

Para receber notificacoes em tempo real (recomendado em vez de polling):

BODY='{"url":"https://seusite.com.br/webhook","events":["pix.received","pix.completed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Proximos Passos

• Autenticacao -- API Key + HMAC (3 camadas de seguranca)
• HMAC-SHA512 -- como assinar requisicoes transacionais
• PIX Cash-In -- gerar cobrancas
• PIX Cash-Out -- enviar PIX por chave
• Extrato -- consultar transacoes
• Webhooks -- notificacoes em tempo real
• Conceitos -- valores, status, external_id, idempotencia e chaves PIX