PIX Cash In -- Generar QR Code

Genera un cobro PIX con QR Code para recepcion de valores en la cuenta asociada a su API Key.

Endpoint

POST /api/external/pix/cash-in

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body (mas informacion)
Idempotency-Key	String	No	Clave unica para evitar procesamiento duplicado (max 256 chars)

Request Body

Campo	Tipo	Obligatorio	Descripcion	Ejemplo
amount	Integer	Si	Valor en centavos (R$ 30,00 = 3000)	3000
description	String	No	Descripcion del cobro (max 140 caracteres)	"Pedido #1234"
external_id	String	No	Identificador de su sistema para rastreo. Max 128 chars. Solo a-zA-Z0-9._:-. Retornado en respuestas y webhooks.	"order-9876"

Valores monetarios

Los valores de entrada son en centavos (R$ 1,00 = 100). Los valores de respuesta son en unidades base (R$ 1,00 = 10000). Para convertir la respuesta a reales, divida por 10.000. Nunca use punto flotante.

Ejemplo

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"

Respuesta de Exito (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	Descripcion
worked	Boolean	true indica exito en la operacion
transaction_id	String	Identificador unico del cobro (tx_id del QR Code)
qr_code	String	Codigo EMV copia y pega para pago
qr_code_image	String	Imagen del QR Code codificada en base64 (PNG)
external_id	String	Su identificador, retornado tal como fue enviado. null si no fue informado
amount	Integer	Valor del cobro en unidades base (/ 10.000 para reales). 300000 = R$ 30,00
status	String	Estado inicial: active (QR Code activo para pago)
expires_at	String	Fecha/hora de expiracion del QR Code (ISO 8601)

Respuesta de Error (400)

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

Respuesta de Error (401)

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

Respuesta de Error (422)

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

Flujo Recomendado

1. Genere el cobro con este endpoint
2. Muestre el QR Code (qr_code_image) o el codigo copia y pega (qr_code) al pagador
3. Reciba la confirmacion via Webhook cuando el pago sea efectuado
4. O consulte el estado: por ID, por E2E, por Tag

Validez del QR Code

El QR Code generado tiene validez de 24 horas. Despues de ese periodo, el cobro expira automaticamente y el estado cambia a cancelled.