PIX Cash In -- Generate QR Code

Generates a PIX charge with a QR Code for receiving payments into the account associated with your API Key.

Endpoint

POST /api/external/pix/cash-in

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}
Content-Type	String	Yes	application/json
hmac	String	Yes	HMAC-SHA512 signature of the body (learn more)
Idempotency-Key	String	No	Unique key to prevent duplicate processing (max 256 chars)

Request Body

Field	Type	Required	Description	Example
amount	Integer	Yes	Amount in centavos (R$ 30.00 = 3000)	3000
description	String	No	Charge description (max 140 characters)	"Pedido #1234"
external_id	String	No	Your system identifier for tracking. Max 128 chars. Only a-zA-Z0-9._:-. Returned in responses and webhooks.	"order-9876"

Monetary values

Request values are in centavos (R$ 1.00 = 100). Response values are in base units (R$ 1.00 = 10000). To convert the response to BRL, divide by 10,000. Never use floating point.

Example

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"

Success Response (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"
}

Field	Type	Description
worked	Boolean	true indicates operation success
transaction_id	String	Unique charge identifier (QR Code tx_id)
qr_code	String	EMV copy-and-paste code for payment
qr_code_image	String	QR Code image encoded in base64 (PNG)
external_id	String	Your identifier, returned as sent. null if not provided
amount	Integer	Charge amount in base units (/ 10,000 for BRL). 300000 = R$ 30.00
status	String	Initial status: active (QR Code active for payment)
expires_at	String	QR Code expiration date/time (ISO 8601)

Error Response (400)

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

Error Response (401)

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

Error Response (422)

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

Recommended Flow

1. Generate the charge with this endpoint
2. Display the QR Code (qr_code_image) or the copy-and-paste code (qr_code) to the payer
3. Receive confirmation via Webhook when payment is made
4. Or query the status: by ID, by E2E, by Tag

QR Code Validity

The generated QR Code is valid for 24 hours. After this period, the charge expires automatically and the status changes to cancelled.