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

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

curl -X POST "https://api.corpxapi.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. Máximo de 2 casas decimais (ex.: 150.75)
`expirationDate`	datetime	Sim	Data/hora de expiração (RFC3339, ex.: `2026-02-10T15:30:00Z`)
`identifier`	string	Sim	Identificador único da cobrança (máximo 35 caracteres)
`message`	string	Não	Mensagem exibida ao pagador (máximo 140 caracteres)
`allowChangeValue`	boolean	Não	Permite alteração do valor no momento do pagamento (padrão: false)
`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)

{
  "statusCode": 201,
  "title": "created",
  "type": "dynamic_immediate",
  "message": "QR code created successfully",
  "data": {
    "chave": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
    "identifier": "order-12345",
    "location": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a908a92441a98dac228ee1d95075204000053039865802BR5912iDez Digital6004Lins62070503***63040BFF",
    "payload": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a908a92441a98dac228ee1d95075204000053039865802BR5912iDez Digital6004Lins62070503***63040BFF",
    "status": "ATIVA",
    "txid": "88a38a908a92441a98dac228ee1d9507"
  }
}

Campo	Descrição
`data.chave`	Chave PIX utilizada na cobrança
`data.identifier`	ID único da cobrança (use para consultas)
`data.payload`	Código PIX Copia e Cola (string EMV)
`data.location`	Mesmo que payload - a string EMV do QR code
`data.status`	Status da cobrança (`ATIVA` = ativa)
`data.txid`	ID interno da transação

Passo 2: Exibir o QR Code

Usando PIX Copia e Cola

Exiba o campo payload para o cliente copiar:

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

dica

Você pode gerar uma imagem de QR code a partir da string payload 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:

Request

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

Status Possíveis

Status	Descrição
`active`	Aguardando pagamento
`paid`	Pagamento confirmado
`refunded`	Pagamento foi devolvido (você devolveu o dinheiro)
`expired`	Cobrança expirou sem pagamento
`cancelled`	Cobrança cancelada manualmente

Exemplos de Resposta por Status

Ativa (aguardando pagamento)

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

Paga (pagamento confirmado)

{
  "txid": "b091da7bba6a45d1a9f709daaba04e30",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 150.75,
  "status": "paid",
  "type": "dynamic",
  "createdAt": "2026-02-05T22:08:02Z",
  "expiresAt": "2026-02-05T23:08:00Z",
  "description": "Payment for order #12345",
  "emv": "00020101021226790014br.gov.bcb.pix...",
  "location": "00020101021226790014br.gov.bcb.pix...",
  "paidAt": "2026-02-05T22:10:25.055",
  "paidAmount": 150.75,
  "endToEndId": "E303062942026020522100000005EXVX",
  "payer": {
    "name": "John Smith",
    "document": "12345678901",
    "bankCode": "30306294",
    "branch": "0020",
    "account": "004912314"
  },
  "reconciled": true,
  "reconciledAt": "2026-02-05T22:10:25Z",
  "transactionId": "e094058f-de94-40a8-99a0-cdd5cb4cc832"
}

Devolvida (você devolveu o pagamento)

Quando você devolve um pagamento recebido usando POST /v1/accounts/{accountId}/pix/out/refund, o status do QR code muda para refunded:

{
  "txid": "b091da7bba6a45d1a9f709daaba04e30",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 150.75,
  "status": "refunded",
  "type": "dynamic",
  "createdAt": "2026-02-05T22:08:02Z",
  "paidAt": "2026-02-05T22:10:25.055",
  "paidAmount": 150.75,
  "endToEndId": "E303062942026020522100000005EXVX",
  "payer": {
    "name": "John Smith",
    "document": "12345678901"
  },
  "reconciled": true,
  "reconciledAt": "2026-02-05T22:10:25Z",
  "transactionId": "e094058f-de94-40a8-99a0-cdd5cb4cc832",
  "refundEndToEndId": "D303062942026020613020000005Ft76",
  "refundedAt": "2026-02-06T13:02:16Z",
  "refundAmount": 150.75,
  "refunds": [
    {
      "id": "refund-001",
      "amount": 150.75,
      "status": "DEVOLVIDO",
      "endToEndId": "D303062942026020613020000005Ft76",
      "requestedAt": "2026-02-06T13:02:00Z",
      "processedAt": "2026-02-06T13:02:16Z"
    }
  ],
  "totalRefundAmount": 150.75
}

Expirada (cobrança expirou)

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

Referência de Campos

Campo	Presente	Descrição
`txid`	Sempre	ID interno da transação do QR code
`identifier`	Sempre	Seu identificador único da cobrança
`value`	Sempre	Valor da cobrança em BRL
`status`	Sempre	Status atual (`active`, `paid`, `refunded`, `expired`, `cancelled`)
`type`	Sempre	Tipo do QR code (`dynamic` ou `static`)
`emv`	Sempre	Código PIX Copia e Cola
`expiresAt`	Sempre	Data de expiração da cobrança
`reconciled`	Sempre	Se está vinculado a uma transação no extrato
`paidAt`	Quando pago	Data/hora do pagamento
`paidAmount`	Quando pago	Valor efetivamente pago em BRL
`endToEndId`	Quando pago	Identificador E2E do PIX (único no sistema PIX)
`payer`	Quando pago	Informações do pagador (name, document, bankCode, branch, account)
`transactionId`	Quando conciliado	ID da transação para consulta no extrato
`refundEndToEndId`	Quando devolvido	Identificador E2E da devolução
`refundedAt`	Quando devolvido	Data/hora da devolução
`refundAmount`	Quando devolvido	Valor devolvido em BRL
`refunds`	Quando devolvido	Array com detalhes das devoluções (suporta devoluções parciais)
`totalRefundAmount`	Quando devolvido	Total de todas as devoluções em BRL

Endpoint de Lookup (busca avançada)

Além da busca por identifier, você pode usar o endpoint dedicado de lookup que aceita busca por qrcodeId (txid) ou endToEndId:

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

# Buscar por txid (qrcodeId)
curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code/lookup?qrcodeId=5774a2eb0e2f40ac" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

# Buscar por E2E (quando pago)
curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code/lookup?endToEndId=E22896431..." \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

informação

Apenas um parâmetro pode ser enviado por vez. O lookup retorna detalhes enriquecidos incluindo dados da transação, payer, fees e refunds relacionados.

Passo 4: Receber Webhook de Pagamento

Quando o cliente pagar, você receberá um webhook pix.in.completed com method: QR_CODE_DYNAMIC:

{
  "event": "qrcode.paid",
  "timestamp": "2026-02-05T22:10:25Z",
  "tenantId": "tenant-yourcompany",
  "data": {
    "identifier": "order-12345",
    "txid": "b091da7bba6a45d1a9f709daaba04e30",
    "status": "PAID",
    "value": 150.75,
    "paidAmount": 150.75,
    "endToEndId": "E303062942026020522100000005EXVX",
    "payer": {
      "name": "John Smith",
      "document": "12345678901"
    }
  }
}

dica

Configure webhooks via POST /v1/webhooks com o tipo de evento qrcode.paid. Veja o Guia de Webhooks.

Passo 5: Cancelar uma Cobrança (Opcional)

Cancele uma cobrança pendente antes de ser paga:

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

Passo 6: Listar Todos os QR Codes

Liste os QR codes de uma conta, opcionalmente filtrados por status:

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-codes?status=PAID" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

Resposta

{
  "items": [
    {
      "txid": "8ab8a37b2e274c8dae51128a379c909a",
      "identifier": "order-67890",
      "status": "paid",
      "value": 50.00,
      "paidAmount": 50.00,
      "endToEndId": "E303062942026020522130000005EYaT",
      "reconciled": true,
      "createdAt": "2026-02-05T22:09:32Z"
    }
  ],
  "count": 1
}

Exemplo Completo: Integração E-commerce

#!/bin/bash

# Configuration
API_URL="https://api.corpxapi.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 '.data.identifier')
PAYLOAD=$(echo $response | jq -r '.data.payload')

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

# 3. Poll for payment (alternative to webhook)
while true; do
  sleep 10
  
  status_response=$(curl -s "$API_URL/v1/accounts/$ACCOUNT_ID/pix/qr-code?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

Use Idempotency Key - Sempre envie um identificador único por cobrança para evitar duplicatas
Defina uma expiração adequada - 30 minutos para checkout, 24h para faturas
Configure webhooks - Não dependa apenas de polling; use eventos qrcode.paid
Todos os valores em BRL - Use no máximo 2 casas decimais (ex.: 150.75 para R$150,75)
Trate a expiração - Notifique o cliente quando a cobrança expirar
Armazene o identifier - Use-o para consultar status e conciliar pagamentos

Erros Comuns

Erro	Causa	Solução
`400 - pixKey is required`	Chave PIX ausente	Inclua uma chave PIX válida cadastrada na conta
`400 - value must be greater than zero`	Valor inválido	Envie um valor positivo em BRL
`400 - value has too many decimal places`	Mais de 2 casas decimais	Use no máximo 2 casas decimais (ex.: 150.75)
`400 - identifier is required`	Identificador ausente	Forneça um identificador único da cobrança
`400 - expirationDate must be a valid RFC3339 timestamp`	Data inválida	Use formato RFC3339 (ex.: `2026-02-10T15:30:00Z`)
`404 - QR code not found`	Cobrança não encontrada	Verifique o identifier e o accountId

Próximos Passos

Guia de Cash Out - Fazer transferências PIX
Guia de Devolução - Devolver pagamentos recebidos
Webhooks - Configurar notificações

Visão Geral​

Fluxo de Integração​

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

Request​

Parâmetros do Body​

Headers Importantes​

Resposta de Sucesso (201 Created)​

Passo 2: Exibir o QR Code​

Usando PIX Copia e Cola​

Passo 3: Consultar Status da Cobrança​

Request​

Status Possíveis​

Exemplos de Resposta por Status​

Ativa (aguardando pagamento)​

Paga (pagamento confirmado)​

Devolvida (você devolveu o pagamento)​

Expirada (cobrança expirou)​

Referência de Campos​

Endpoint de Lookup (busca avançada)​

Passo 4: Receber Webhook de Pagamento​

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

Passo 6: Listar Todos os QR Codes​

Resposta​

Exemplo Completo: Integração E-commerce​

Boas Práticas​

Erros Comuns​

Próximos Passos​

Visão Geral

Fluxo de Integração

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

Request

Parâmetros do Body

Headers Importantes

Resposta de Sucesso (201 Created)

Passo 2: Exibir o QR Code

Usando PIX Copia e Cola

Passo 3: Consultar Status da Cobrança

Request

Status Possíveis

Exemplos de Resposta por Status

Ativa (aguardando pagamento)

Paga (pagamento confirmado)

Devolvida (você devolveu o pagamento)

Expirada (cobrança expirou)

Referência de Campos

Endpoint de Lookup (busca avançada)

Passo 4: Receber Webhook de Pagamento

Passo 5: Cancelar uma Cobrança (Opcional)

Passo 6: Listar Todos os QR Codes

Resposta

Exemplo Completo: Integração E-commerce

Boas Práticas

Erros Comuns

Próximos Passos