143 lines
5.4 KiB
Markdown
143 lines
5.4 KiB
Markdown
---
|
|
title: "Static Pix QR Code: How It Works and Developer Responsibilities"
|
|
description: "Understand what a static Pix QR Code is, how it is generated by the API, its limitations, and why payment verification is your application's responsibility — not QRRapido's."
|
|
keywords: "pix qr code, static pix, pix qr code api, pix qr code integration, pix without central bank"
|
|
author: "QRRapido"
|
|
date: 2026-03-08
|
|
lastmod: 2026-03-08
|
|
image: ""
|
|
---
|
|
|
|
# Static Pix QR Code: How It Works and Developer Responsibilities
|
|
|
|
## What is a Static Pix QR Code?
|
|
|
|
Pix has two types of QR codes: **static** and **dynamic**.
|
|
|
|
| | Static Pix | Dynamic Pix |
|
|
|---|---|---|
|
|
| Amount | Variable (payer decides) | Fixed (set by recipient) |
|
|
| Generation | Any system | PSP/Central Bank intermediary |
|
|
| Central Bank registration | **No** | Yes |
|
|
| Payment notification | **No** | Yes (webhook) |
|
|
| Typical use | Donations, simple charges | E-commerce, tracked billing |
|
|
|
|
The QRRapido API generates **exclusively static Pix QR codes**. This is deliberate and sufficient for most use cases.
|
|
|
|
---
|
|
|
|
## How the API Generates the Pix QR Code
|
|
|
|
When you send a request with `type: "pix"`, the API assembles a string in the **EMV® QR Code** standard (the international standard adopted by Brazil's Central Bank) and generates the image:
|
|
|
|
```json
|
|
{
|
|
"type": "pix",
|
|
"content": "contact@yourcompany.com"
|
|
}
|
|
```
|
|
|
|
The `content` field must contain **only the Pix key** of the recipient. The API handles assembling the EMV payload correctly.
|
|
|
|
**Accepted keys:**
|
|
- Email: `contact@company.com`
|
|
- CPF/CNPJ: digits only — `12345678901` or `12345678000195`
|
|
- Phone: `+5511999999999`
|
|
- Random key (EVP): `123e4567-e89b-12d3-a456-426614174000`
|
|
|
|
---
|
|
|
|
## What the API Does NOT Do (and Why This Matters)
|
|
|
|
> **QRRapido has no integration with the Central Bank, any bank, or any PSP (Payment Service Provider).**
|
|
|
|
This means:
|
|
|
|
1. **The API does not know if the payment was made.** It only generates the QR code image. What happens after — whether the customer scanned it, whether the Pix was sent, whether it landed in the right account — is outside the scope of the API.
|
|
|
|
2. **There is no payment confirmation webhook.** The API does not send notifications when a Pix is received.
|
|
|
|
3. **The QR code does not expire automatically.** A static Pix QR code is valid indefinitely (or until the Pix key is removed by the recipient at the bank).
|
|
|
|
4. **There is no transaction traceability.** Two requests with the same key generate the same QR code (with cache). It is not possible to associate a scan with a specific transaction via the API.
|
|
|
|
---
|
|
|
|
## Your Application's Responsibility
|
|
|
|
If you use the API to generate Pix QR codes in a payment flow, **it is your application's responsibility to verify receipt**. The correct ways to do this are:
|
|
|
|
### Option 1 — Recipient's Bank Pix API
|
|
Connect directly to the Pix API of the bank where the key is registered. Most banks offer:
|
|
- Query of received charges
|
|
- Real-time notification webhook (when the bank supports it)
|
|
|
|
### Option 2 — PSP / Payment Gateway
|
|
Use an intermediary such as Mercado Pago, PagSeguro, Efí Bank, Asaas, etc. They offer dynamic Pix with full control: fixed amount, expiration, webhooks and unique identification per charge.
|
|
|
|
### Option 3 — Manual Verification
|
|
For low volumes or informal contexts (donations, in-person sales), the person responsible for receiving verifies the bank statement manually.
|
|
|
|
---
|
|
|
|
## Recommended Flow (with confirmation)
|
|
|
|
```
|
|
Your App QRRapido API Recipient's Bank
|
|
| | |
|
|
|-- POST /generate (pix) -->| |
|
|
|<-- qrCodeBase64 ----------| |
|
|
| | |
|
|
|-- Shows QR to customer | |
|
|
| | |
|
|
|-- Query payment ---------------------------------->|
|
|
|<-- Received status or not --------------------------|
|
|
| | |
|
|
|-- Releases product/service| |
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Request Example
|
|
|
|
```bash
|
|
curl -X POST https://qrrapido.site/api/v1/QRManager/generate \
|
|
-H "X-API-Key: your_key_here" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"content": "contact@yourcompany.com",
|
|
"type": "pix",
|
|
"size": 400,
|
|
"outputFormat": "webp"
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
## Appropriate Use Cases for Static Pix via API
|
|
|
|
- Donation QR code on an institutional website
|
|
- Digital menu with key for in-person payment
|
|
- Batch QR generation for printed materials (flyers, cards)
|
|
- Applications where the seller and buyer interact in person and the seller confirms receipt in the bank app
|
|
|
|
## Use Cases That Require Dynamic Pix (not supported by this API)
|
|
|
|
- E-commerce with automatic order confirmation
|
|
- Fixed-amount billing with expiration
|
|
- Invoice issuance linked to payment
|
|
- Automated financial reconciliation
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| What the API does | What the API does NOT do |
|
|
|---|---|
|
|
| Generates the Pix QR code image | Verifies if the payment was made |
|
|
| Formats the EMV payload correctly | Sends confirmation webhook |
|
|
| Delivers PNG, WebP or SVG | Communicates with the Central Bank or banks |
|
|
| Works with any valid Pix key | Guarantees the key belongs to who claims it does |
|
|
|
|
Correct QR code generation is the API's responsibility. **Payment confirmation is your application's responsibility.**
|