Skip to main content

​
Overview

The PIX IN flow allows you to receive payments to your Owem account. There are two main ways:
  1. Dynamic QR Code - You generate a QR Code with a specific amount
  2. PIX Key - Customer pays directly to your key
Dynamic QR Code is the most common and recommended way for e-commerce and one-time payments.

​
Complete Flow

​
Step 1: Generate QR Code

curl -X POST "https://api.owem.com.br/v4/i/pix/in/dynamic-qrcode" \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "123456789012",
    "userId": "usr_abc123def",
    "amount": 150.00,
    "description": "Order #12345",
    "expirationSeconds": 3600,
    "payerName": "JOHN DOE",
    "payerCpfCnpj": "12345678900"
  }'
Bradesco and Caixa Econômica Federal require payerName and payerCpfCnpj. Without these fields, the QR won’t work on these banks.

​
Step 2: Display QR Code

Use the returned emv field to generate the QR Code image. Example with qrcode library: 
import QRCode from "qrcode"

// Generate base64 image of QR Code
const qrImage = await QRCode.toDataURL(data.data.emv)

// Use in HTML
document.getElementById("qrcode").src = qrImage

​
Step 3: Wait for Payment

There are two ways to know when payment is made: Configure a webhook for the pix_in:qrcode_paid event. You’ll receive a notification as soon as payment is confirmed. 
{
  "webhookId": "wh_abc123",
  "event": "pix_in:qrcode_paid",
  "object": {
    "endToEndId": "E123456789...",
    "entryId": "abc123def456...",
    "status": "succeeded",
    "grossAmount": 150.0,
    "netAmount": 149.85
  }
}

​
Option B: Polling

Query the status periodically using the txId: 
curl -X GET "https://api.owem.com.br/v4/i/ledger/entry-id/{txId}" \
  -u "API_KEY:API_SECRET"
The txId returned when creating the QR is the same as entryId in the Ledger.

​
Step 4: Confirm in Ledger

After receiving the webhook or detecting payment, confirm in the Ledger: 
curl -X GET "https://api.owem.com.br/v4/i/ledger/entry-id/{txId}" \
  -u "API_KEY:API_SECRET"
Check:
  • status: "succeeded" → Payment confirmed
  • netAmount → Net amount credited

​
Refund a Payment

If you need to return the amount to the payer: 
curl -X POST "https://api.owem.com.br/v4/i/pix/in/refund/{endToEndId}" \
  -u "API_KEY:API_SECRET"
Refunds are subject to PIX arrangement rules and may have limited timeframes.

​
Best Practices

Increases conversion rate by up to 10% and ensures compatibility with all banks.
Webhooks are more efficient and notify instantly. Polling consumes more resources and has delay.
The Ledger is the source of truth. Always confirm status before releasing products/services.
For checkouts, use 10-30 minutes. For virtual invoices, use 24-48 hours.
EventWhen it occurs
pix_in:qrcode_paidQR Code payment confirmed
pix_in:creditedCredit via PIX key
pix_in:refunded_processingRefund initiated

​
Next Steps

Configure Webhooks

Receive real-time notifications

API Reference

Complete endpoint documentation