Primeiros Passos

Integre sua aplicação com a API da Owem Pay e realize sua primeira operação 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 autenticação e assinatura HMAC (prefixo sk_)

Segurança

Nunca exponha o client_secret em código frontend ou repositórios públicos. Utilize variáveis de ambiente no seu servidor.

2. Configure a autenticação

Todas as requisições exigem o header Authorization com suas credenciais API Key:

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

A API Key é permanente -- não expira. Não é necessário gerar tokens.

3. Consulte o saldo

Teste a integração 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 monetários

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

4. Gere uma cobrança 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 você enviou 3000 (centavos) e recebeu 300000 (unidades base). Ambos representam R$ 30,00.

Exiba o qr_code_image ou o código 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.

Você também 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 notificações (Webhooks)

Para receber notificações em tempo real (recomendado em vez de polling):

BODY='{"url":"https://seusite.com.br/webhook","events":["pix.charge.paid","pix.payout.confirmed"]}'
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"

Próximos Passos

• Autenticação -- API Key + HMAC (3 camadas de segurança)
• HMAC-SHA512 -- como assinar requisições transacionais
• PIX Cash-In -- gerar cobranças
• PIX Cash-Out -- enviar PIX por chave
• Extrato -- consultar transações
• Webhooks -- notificações em tempo real
• Conceitos -- valores, status, external_id, idempotência e chaves PIX