PIX Cash In -- Gerar QR Code

Gera uma cobranca PIX com QR Code para recebimento de valores na conta associada a sua API Key.

Endpoint

POST /api/external/pix/cash-in

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body (saiba mais)
Idempotency-Key	String	Nao	Chave unica para evitar processamento duplicado (max 256 chars)

Request Body

Campo	Tipo	Obrigatorio	Descricao	Exemplo
amount	Integer	Sim	Valor em centavos (R$ 30,00 = 3000)	3000
description	String	Nao	Descricao da cobranca (max 140 caracteres)	"Pedido #1234"
external_id	String	Nao	Identificador do seu sistema para rastreamento. Max 128 chars. Apenas a-zA-Z0-9._:-. Retornado em respostas e webhooks.	"order-9876"

Valores monetarios

Valores de entrada sao em centavos (R$ 1,00 = 100). Valores de resposta sao em unidades base (R$ 1,00 = 10000). Para converter a resposta para reais, divida por 10.000. Nunca use ponto flutuante.

Exemplo

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 de Sucesso (200)

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,iVBORw0KGgo...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active",
  "expires_at": "2026-03-07T16:30:00Z"
}

Campo	Tipo	Descricao
worked	Boolean	true indica sucesso na operacao
transaction_id	String	Identificador unico da cobranca (tx_id do QR Code)
qr_code	String	Codigo EMV copia-e-cola para pagamento
qr_code_image	String	Imagem do QR Code codificada em base64 (PNG)
external_id	String	Seu identificador, retornado tal como enviado. null se nao informado
amount	Integer	Valor da cobranca em unidades base (÷ 10.000 para reais). 300000 = R$ 30,00
status	String	Status inicial: active (QR Code ativo para pagamento)
expires_at	String	Data/hora de expiracao do QR Code (ISO 8601)

Resposta de Erro (400)

{
  "worked": false,
  "detail": "O campo amount e obrigatorio"
}

Resposta de Erro (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Resposta de Erro (422)

{
  "worked": false,
  "detail": "Invalid HMAC signature"
}

Fluxo Recomendado

1. Gere a cobranca com este endpoint
2. Exiba o QR Code (qr_code_image) ou o codigo copia-e-cola (qr_code) ao pagador
3. Receba a confirmacao via Webhook quando o pagamento for efetuado
4. Ou consulte o status: por ID, por E2E, por Tag

Validade do QR Code

O QR Code gerado tem validade de 24 horas. Apos esse periodo, a cobranca expira automaticamente e o status muda para cancelled.