> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Guia de QR Code Dinâmico

Este guia explica como gerar cobranças PIX utilizando QR Codes dinâmicos.

## Visão Geral

O QR Code Dinâmico permite criar cobranças únicas com valor definido, data de expiração e informações do pagador. É ideal para:

* **E-commerce** - Pagamentos de pedidos
* **Faturamento** - Faturas e boletos
* **Serviços** - Pagamento por serviços prestados

Para um código reutilizável, que aceita vários pagamentos e não expira — placa
no balcão, doação, mensalidade —, veja o
[Guia de QR Code Estático](/baas/guias/receber/qr-code-estatico).

## Fluxo de Integração

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Criar     │      │   Cliente   │      │   Webhook   │
│   Cobrança  │ ───► │   Paga QR   │ ───► │   Recebido  │
└─────────────┘      └─────────────┘      └─────────────┘
      │                                          │
      ▼                                          ▼
  Retorna EMV                              Confirma
  e payload                                Pagamento
```

## Passo 1: Criar uma Cobrança (QR Code Dinâmico)

### Request

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/dynamic" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "pixKey": "your-pix-key-here",
    "value": 150.75,
    "expirationDate": "2026-02-10T15:30:00Z",
    "identifier": "order-12345",
    "message": "Payment for order #12345"
  }'
```

### Parâmetros do Body

| Campo                   | Tipo     | Obrigatório | Descrição                                                                                                                                                                                                                                                 |
| ----------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pixKey`                | string   | Sim         | Chave PIX da conta recebedora (deve estar cadastrada)                                                                                                                                                                                                     |
| `value`                 | number   | Sim         | Valor da cobrança em BRL, maior que zero. Máximo de 2 casas decimais (ex.: 150.75)                                                                                                                                                                        |
| `expirationDate`        | datetime | Não         | Data/hora de expiração (RFC3339, ex.: `2026-02-10T15:30:00Z`), no máximo 90 dias depois da criação. Sem ela o QR expira em 24 horas. A conta pode ter um limite menor configurado no liquidante; acima dele a resposta é 400 com a mensagem do liquidante |
| `identifier`            | string   | Recomendado | Identificador único da cobrança (máximo 38 caracteres, charset `[A-Za-z0-9._-]`). Se omitido, a API gera um UUID sem hifens                                                                                                                               |
| `message`               | string   | Não         | Mensagem exibida ao pagador (máximo 140 caracteres)                                                                                                                                                                                                       |
| `allowedPayerTaxNumber` | string   | Não         | CPF/CNPJ específico autorizado a pagar                                                                                                                                                                                                                    |

### Headers Importantes

| Header            | Descrição                                            |
| ----------------- | ---------------------------------------------------- |
| `Idempotency-Key` | Identificador único para evitar cobranças duplicadas |

### Resposta de Sucesso (201 Created)

```json
{
  "txid": "88a38a908a92441a98dac228ee1d9507",
  "emv": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a908a92441a98dac228ee1d95075204000053039865802BR5912iDez Digital6004Lins62070503***63040BFF",
  "type": "dynamic",
  "status": "ACTIVE",
  "value": 150.75,
  "message": "Payment for order #12345",
  "description": "Payment for order #12345",
  "identifier": "order-12345",
  "accountId": "{accountId}",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "allowChange": false,
  "createdAt": "2026-02-10T12:00:00Z",
  "expiresAt": "2026-02-10T15:30:00Z"
}
```

> **Sem envelope \`data\`**
>
> A resposta é um objeto **plano** (top-level). Não há envelope `data` nem
> os campos `statusCode`/`title`/`message`. O código copia-e-cola está em
> `emv` (não `data.payload`) e a chave em `pixKey` (não `data.chave`).

| Campo        | Descrição                                                |
| ------------ | -------------------------------------------------------- |
| `emv`        | Código PIX Copia e Cola (string EMV). Renderize como QR. |
| `txid`       | ID interno da transação                                  |
| `identifier` | ID único da cobrança (use para consultas)                |
| `status`     | Status da cobrança (`ACTIVE` = ativa)                    |
| `pixKey`     | Chave PIX utilizada na cobrança                          |
| `value`      | Valor da cobrança em BRL                                 |
| `expiresAt`  | Data/hora de expiração (RFC3339)                         |

## Passo 2: Exibir o QR Code

### Usando PIX Copia e Cola

Exiba o campo `emv` para o cliente copiar:

```html
<input type="text" 
       value="00020101021226790014br.gov.bcb.pix..." 
       readonly />
<button onclick="navigator.clipboard.writeText(this.previousElementSibling.value)">
  Copy
</button>
```

> **Tip**
>
> Você pode gerar uma imagem de QR code a partir da string `emv` usando qualquer biblioteca de QR code (ex.: `qrcode.js`, `python-qrcode`).

## Passo 3: Consultar Status da Cobrança

Consulte o status de uma cobrança pelo seu `identifier`:

> **Credencial só de QR code**
>
> O escopo `qrcode.manage` cobre criar, cancelar **e consultar** o QR: uma
> credencial dedicada a cobranças enxerga se o QR foi pago sem precisar do escopo
> de consulta geral (`read`), que dá acesso a saldo e extrato. Ver o
> [Guia de Autenticação](/baas/guias/autenticacao/oauth2).

### Request

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/lookup?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"
```

### Status Possíveis

| Status             | Descrição                                       |
| ------------------ | ----------------------------------------------- |
| `ACTIVE`           | Criado / aguardando                             |
| `AWAITING-PAYMENT` | Aguardando pagamento                            |
| `PAID`             | Pagamento confirmado                            |
| `CANCELLED`        | Cancelado / rejeitado                           |
| `EXPIRED`          | Expirou sem pagamento                           |
| `UNKNOWN`          | Status do parceiro fora do mapeamento conhecido |

> **Valores em MAIÚSCULAS**
>
> O `status` é retornado em **MAIÚSCULAS** (canônico). Uma devolução de PIX
> **não** muda o status do QR para "refunded" — o QR permanece `PAID` e a
> devolução é acompanhada pela transação/extrato.

### Exemplos de Resposta por Status

#### Ativa (aguardando pagamento)

```json
{
  "txid": "88a38a908a92441a98dac228ee1d9507",
  "emv": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a90...",
  "type": "dynamic",
  "status": "ACTIVE",
  "value": 150.75,
  "description": "Payment for order #12345",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "createdAt": "2026-02-09T01:50:36Z",
  "expiresAt": "2026-02-09T02:50:34Z"
}
```

#### Paga (pagamento confirmado)

```json
{
  "txid": "b091da7bba6a45d1a9f709daaba04e30",
  "emv": "00020101021226790014br.gov.bcb.pix...",
  "type": "dynamic",
  "status": "PAID",
  "value": 150.75,
  "message": "Payment for order #12345",
  "description": "Payment for order #12345",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "allowChange": false,
  "createdAt": "2026-02-05T22:08:02Z",
  "expiresAt": "2026-02-05T23:08:00Z",
  "paidAt": "2026-02-05T22:10:25Z",
  "paidAmount": 150.75,
  "endToEndId": "E303062942026020522100000005EXVX",
  "payer": {
    "name": "John Smith",
    "document": "12345678901",
    "bankIspb": "30306294",
    "bankName": "BANCO EXEMPLO",
    "branch": "0020",
    "account": "004912314"
  },
  "payee": {
    "name": "iDez Digital",
    "document": "12345678000190",
    "bankIspb": "50871921",
    "bankCode": "681"
  }
}
```

#### Após uma devolução

Uma devolução de PIX (`POST /v1/accounts/{accountId}/pix/out/refund`) **não**
muda o status do QR para "refunded" — o QR permanece `PAID`. A devolução é uma
transação separada; acompanhe-a pelo extrato (`GET .../statement`) ou pelo
lookup de pagamento (`GET .../pix/payments/lookup`). O lookup de QR **não**
retorna campos de devolução.

#### Expirada (cobrança expirou)

```json
{
  "txid": "c1234567890abcdef1234567890abcde",
  "emv": "00020101021226790014br.gov.bcb.pix...",
  "type": "dynamic",
  "status": "EXPIRED",
  "value": 50.00,
  "identifier": "order-99999",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "createdAt": "2026-02-01T10:00:00Z",
  "expiresAt": "2026-02-01T10:30:00Z"
}
```

### Referência de Campos

| Campo        | Presente          | Descrição                                                                              |
| ------------ | ----------------- | -------------------------------------------------------------------------------------- |
| `txid`       | Sempre            | ID interno da transação do QR code                                                     |
| `emv`        | Sempre            | Código PIX Copia e Cola (BR Code)                                                      |
| `type`       | Sempre            | Tipo do QR code (`dynamic` ou `static`)                                                |
| `status`     | Sempre            | Status atual (`ACTIVE`, `AWAITING-PAYMENT`, `PAID`, `CANCELLED`, `EXPIRED`, `UNKNOWN`) |
| `value`      | Sempre            | Valor da cobrança em BRL                                                               |
| `identifier` | Sempre            | Seu identificador único da cobrança                                                    |
| `accountId`  | Sempre            | Conta dona da cobrança                                                                 |
| `pixKey`     | Quando disponível | Chave PIX da cobrança                                                                  |
| `createdAt`  | Quando disponível | Data/hora de criação                                                                   |
| `expiresAt`  | Quando disponível | Data de expiração (QR dinâmico)                                                        |
| `paidAt`     | Quando pago       | Data/hora do pagamento                                                                 |
| `paidAmount` | Quando pago       | Valor efetivamente pago em BRL                                                         |
| `endToEndId` | Quando pago       | Identificador E2E do PIX                                                               |
| `payer`      | Quando pago       | Dados do pagador (name, document, bankIspb, bankName, branch, account, pixKey)         |
| `payee`      | Quando disponível | Dados do recebedor (sua conta)                                                         |

### Endpoint de Lookup

A busca é feita por `identifier` (alias retrocompat: `txid`):

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/lookup?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"
```

> **Info**
>
> O lookup é resolvido em **tempo real** no parceiro e retorna o objeto plano do
> QR (status, valor, `emv` e — quando pago — `payer`/`payee`/`endToEndId`). Este
> endpoint **não** aceita busca por `qrcodeId`/`endToEndId` e **não** retorna
> dados de transação/fees/refunds.

## Passo 4: Receber Webhook de Pagamento

Quando o cliente pagar, você receberá um webhook `qrcode.paid` no envelope
canônico (`id`, `type`, `occurredAt`, `schemaVersion`, `data`):

```json
{
  "id": "evt_987654321",
  "type": "qrcode.paid",
  "occurredAt": "2026-02-05T22:10:25.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "{accountId}",
  "data": {
    "endToEnd": "E303062942026020522100000005EXVX",
    "type": "dynamic",
    "identifier": "order-12345",
    "qrcodeId": "b091da7bba6a45d1a9f709daaba04e30",
    "amount": 150.75,
    "payer": {
      "name": "John Smith",
      "document": "12345678901",
      "bankCode": "033",
      "branch": "0001",
      "accountNumber": "54321-0"
    },
    "payee": {
      "name": "iDez Digital",
      "document": "12345678000190"
    },
    "receivedAt": "2026-02-05T22:10:25.000Z"
  }
}
```

> **Tip**
>
> Configure webhooks via `POST /v1/webhooks` com o tipo de evento `qrcode.paid`. Veja o [Guia de Webhooks](/baas/guias/conta/webhooks).

## Passo 5: Cancelar uma Cobrança (Opcional)

Cancele uma cobrança pendente antes de ser paga:

```bash
curl -X DELETE "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"
```

Resposta (200 OK):

```json
{
  "identifier": "order-12345",
  "status": "CANCELLED"
}
```

## Passo 6: Métricas de QR Codes (opcional)

Não há endpoint de **listagem** de QR codes — a consulta é sempre por
`identifier` (lookup). Para métricas agregadas por dia (gerados/pagos/
devolvidos/valor), use:

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-codes/stats?days=30" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"
```

## Exemplo Completo: Integração E-commerce

```bash
#!/bin/bash

# Configuration
API_URL="https://tenant.api.corpx.com"
TOKEN="your_token_here"
TENANT_ID="tenant-yourcompany"
ACCOUNT_ID="your-account-id"
PIX_KEY="your-pix-key"

# 1. Create charge for order
ORDER_ID="order-$(date +%s)"
AMOUNT=299.90
EXPIRATION=$(date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")  # 30 minutes

echo "Creating charge: $ORDER_ID for R\$$AMOUNT..."

response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/qr-code/dynamic" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ORDER_ID" \
  -d "{
    \"pixKey\": \"$PIX_KEY\",
    \"value\": $AMOUNT,
    \"expirationDate\": \"$EXPIRATION\",
    \"identifier\": \"$ORDER_ID\",
    \"message\": \"Store Purchase - $ORDER_ID\"
  }")

# 2. Extract information
IDENTIFIER=$(echo $response | jq -r '.identifier')
EMV=$(echo $response | jq -r '.emv')

echo "Charge created!"
echo "ID: $IDENTIFIER"
echo "PIX Copy and Paste: $EMV"

# 3. Acompanhar o QR (alternativa ao webhook). O laço abaixo lê o status
# da cobrança. Com o QR em PAID, o endToEndId da resposta consulta o
# crédito no lookup de pagamento; com waitForFinalStatus a chamada espera
# até 10 s se o liquidante ainda não tiver liquidado o crédito:
# GET .../pix/payments/lookup?endToEnd=$E2E&waitForFinalStatus=10
while true; do
  sleep 10
  
  status_response=$(curl -s "$API_URL/v1/accounts/$ACCOUNT_ID/pix/qr-code/lookup?identifier=$IDENTIFIER" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-Id: $TENANT_ID")
  
  current_status=$(echo $status_response | jq -r '.status')
  
  if [ "$current_status" = "PAID" ]; then
    paid_amount=$(echo $status_response | jq -r '.paidAmount')
    e2e=$(echo $status_response | jq -r '.endToEndId')
    echo "Payment confirmed! Amount: R\$$paid_amount, E2E: $e2e"
    break
  elif [ "$current_status" = "EXPIRED" ]; then
    echo "Charge expired"
    break
  fi
  
  echo "Awaiting payment... Status: $current_status"
done
```

## Boas Práticas

1. **Use Idempotency Key** - Sempre envie um identificador único por cobrança para evitar duplicatas
2. **Defina uma expiração adequada** - 30 minutos para checkout, 24h para faturas
3. **Configure webhooks** - Não dependa apenas de polling; use eventos `qrcode.paid`. Para confirmar o crédito na mesma chamada, consulte o pagamento pelo `endToEndId` que o lookup do QR devolve: `GET .../pix/payments/lookup?endToEnd={endToEndId}&waitForFinalStatus=10`
4. **Todos os valores em BRL** - Use no máximo 2 casas decimais (ex.: `150.75` para R\$150,75)
5. **Trate a expiração** - Notifique o cliente quando a cobrança expirar
6. **Armazene o identifier** - Use-o para consultar status e conciliar pagamentos

## Erros Comuns

Os erros vêm no formato `{ "errorCode": "...", "message": "..." }`:

| `errorCode`          | HTTP | Causa                                                                                     | Solução                                                                               |
| -------------------- | ---- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `missing_field`      | 400  | `pixKey` ausente ou `value` menor ou igual a zero                                         | Envie uma chave cadastrada e um valor positivo em BRL                                 |
| `invalid_identifier` | 400  | `identifier` fora do charset `[A-Za-z0-9._-]` ou acima de 38 caracteres                   | Ajuste o identificador                                                                |
| `invalid_field`      | 400  | `message` acima de 140 caracteres ou com caracteres não aceitos                           | Encurte a mensagem                                                                    |
| `invalid_payload`    | 400  | JSON malformado, `expirationDate` fora do RFC3339, no passado ou mais de 90 dias à frente | Corrija o corpo da requisição                                                         |
| `missing_param`      | 400  | Lookup/cancelamento sem `identifier` na query                                             | Informe `?identifier=` (alias: `txid`)                                                |
| `not_found`          | 404  | Cobrança não encontrada                                                                   | Verifique o identifier e o accountId                                                  |
| `policy_denied`      | 422  | Uma regra de política recusou a criação da cobrança                                       | Veja `violations` no corpo — [Políticas e Regras](/baas/guias/autenticacao/politicas) |

Exemplo:

```json
{
  "errorCode": "missing_field",
  "message": "pixKey and positive value are required"
}
```

## Próximos Passos

* [Guia de Cash Out](/baas/guias/pagar/pix-out) - Fazer transferências PIX
* [Guia de Devolução](/baas/guias/pagar/devolucao) - Devolver pagamentos recebidos
* [Webhooks](/baas/guias/conta/webhooks) - Configurar notificações