Receber por QR

QR Dinâmico reutilizável — criar, gerenciar, definir valor, buscar e remover.

QR PIX dinâmico, endpoint canônico

Substitui POST /v1/deposit/create (temporariamente bloqueado).

Aceita valor opcional via defaultAmountInCents: com valor, QR dinâmico de cobrança; sem valor, pagador escolhe.

Configure webhooks em vez de pollar /v1/transactions.

Visão geral

QR Dinâmico identificado por slug. Pode aceitar valor variável (pagador informa) ou ter valor padrão fixo. Ideal para pontos de venda físicos, cobranças recorrentes e situações em que o mesmo QR é compartilhado para múltiplas transações.

Alias deprecado: /v1/depix/static-qr

Criar QR code

POST /v1/qr/create

Scope: links
Rate limit: 10 req/min, burst 2/5s
Idempotência obrigatória (X-DF-Idempotency-Key UUID v4)

Cria um novo QR Dinâmico associado ao slug informado. O slug fica disponível na URL pública (https://deflow.exchange/qr/:slug) e pode ser compartilhado.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
slug	string (1-100)	Sim	Identificador único (1-100 chars, letras/dígitos/hifens, sem hifen no início/fim).
defaultAmountInCents	integer \| null	Não	Valor padrão em centavos. Use null (ou omita) para QR de valor variável.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/qr/create \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase" \
  -H "X-DF-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "caixa-loja-01",
    "defaultAmountInCents": null
  }'

Exemplo de resposta da requisição

json

{
  "data": {
    "slug": "caixa-loja-01",
    "url": "https://deflow.exchange/qr/caixa-loja-01",
    "defaultAmountInCents": null,
    "amountFixed": false,
    "feePercent": "1.50",
    "minAmountInCents": 100,
    "maxAmountInCents": 1000000,
    "isDefault": false
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Buscar todos os QR codes

GET /v1/qr

Scope: links + read
Rate limit: 30 req/min, burst 5/5s

Lista todos os QR codes ativos da conta, com URL pública, valor padrão, flag amountFixed e limites permitidos.

Exemplo de requisição

bash

curl https://api.deflow.exchange/v1/qr \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase"

Exemplo de resposta da requisição

json

{
  "data": [
    {
      "slug": "caixa-loja-01",
      "url": "https://deflow.exchange/qr/caixa-loja-01",
      "defaultAmountInCents": null,
      "amountFixed": false,
      "feePercent": "1.50",
      "minAmountInCents": 100,
      "maxAmountInCents": 1000000,
      "isDefault": false
    },
    {
      "slug": "caixa-loja-02",
      "url": "https://deflow.exchange/qr/caixa-loja-02",
      "defaultAmountInCents": 5000,
      "amountFixed": true,
      "feePercent": "1.50",
      "minAmountInCents": 100,
      "maxAmountInCents": 1000000,
      "isDefault": false
    }
  ],
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Buscar QR code por slug

GET /v1/qr/:slug

Scope: read
Rate limit: 60 req/min, burst 10/5s

Retorna detalhes de um QR específico pelo slug. Use para inspecionar amountFixed atual, feePercent, min/max e flag isDefault.

Exemplo de requisição

bash

curl https://api.deflow.exchange/v1/qr/caixa-loja-01 \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase"

Exemplo de resposta da requisição

json

{
  "data": {
    "slug": "caixa-loja-01",
    "url": "https://deflow.exchange/qr/caixa-loja-01",
    "defaultAmountInCents": null,
    "amountFixed": false,
    "feePercent": "1.50",
    "minAmountInCents": 100,
    "maxAmountInCents": 1000000,
    "isDefault": false
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Definir valor padrão

POST /v1/qr/update

Scope: links
Rate limit: 15 req/min, burst 3/5s

Define um valor padrão em centavos para o QR. Após esta operação, amountFixed passa a ser true e o pagador NÃO pode informar valor diferente.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
defaultAmountInCents	integer > 0	Sim	Valor padrão em centavos. Inteiro positivo dentro de minAmountInCents..maxAmountInCents.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/qr/update \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase" \
  -H "Content-Type: application/json" \
  -d '{ "defaultAmountInCents": 5000 }'

Exemplo de resposta da requisição

json

{
  "data": {
    "slug": "caixa-loja-01",
    "url": "https://deflow.exchange/qr/caixa-loja-01",
    "defaultAmountInCents": 5000,
    "amountFixed": true,
    "feePercent": "1.50",
    "minAmountInCents": 100,
    "maxAmountInCents": 1000000,
    "isDefault": false
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Remover definição de valor

POST /v1/qr/update

Scope: links
Rate limit: 15 req/min, burst 3/5s

Remove a definição de valor padrão enviando defaultAmountInCents: null. Após esta operação, amountFixed volta para false e o pagador escolhe o valor a pagar.

Atenção: isto NÃO deleta o QR. O slug, URL e demais propriedades continuam ativos. Para remover o QR permanentemente, use DELETE.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
defaultAmountInCents	null	Sim	Envie null (ou JSON null) para remover a definição.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/qr/update \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase" \
  -H "Content-Type: application/json" \
  -d '{ "defaultAmountInCents": null }'

Exemplo de resposta da requisição

json

{
  "data": {
    "slug": "caixa-loja-01",
    "url": "https://deflow.exchange/qr/caixa-loja-01",
    "defaultAmountInCents": null,
    "amountFixed": false,
    "feePercent": "1.50",
    "minAmountInCents": 100,
    "maxAmountInCents": 1000000,
    "isDefault": false
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Deletar QR code

POST /v1/qr/delete

Scope: links
Rate limit: 10 req/min, burst 3/5s

Remove permanentemente o QR. A URL pública deixa de aceitar pagamentos e o slug fica liberado para reuso futuro.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/qr/delete \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase"

Exemplo de resposta da requisição

json

{
  "data": {
    "slug": "caixa-loja-01",
    "status": "cancelled",
    "cancelledAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Gerar pagamento

POST /v1/qr/pay

Scope: transact
Rate limit: 30 req/min, burst 5/5s
Idempotência obrigatória (X-DF-Idempotency-Key UUID v4)

Gera um pagamento usando um QR Dinâmico existente do próprio usuário. Retorna um jobId; o status pode ser acompanhado via webhooks deposit:paid/deposit:expired.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
amountInCents	integer > 0	Sim	Valor em centavos a pagar. Inteiro positivo. Para QR com valor fixo, deve bater exatamente com defaultAmountInCents.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/qr/caixa-loja-01/pay \
  -H "Authorization: Bearer dfk_live_..." \
  -H "X-DF-Secret: sk_..." \
  -H "X-DF-Passphrase: minha-passphrase" \
  -H "X-DF-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amountInCents": 2500}'

Exemplo de resposta da requisição

json

{
  "data": {
    "jobId": "ee01d4f4-64e5-40d6-a975-3abf0b1243b5"
  },
  "meta": {
    "timestamp": "2026-05-16T05:02:39.699Z"
  }
}

Valor fixo vs variável

O comportamento do QR muda conforme defaultAmountInCents. O campo amountFixed é derivado: true quando defaultAmountInCents está definido, false caso contrário.

amountFixed: true — amountFixed=true (defaultAmountInCents definido). Valor pré-definido; o app do banco já mostra o valor e o pagador não pode editar.
amountFixed: false — amountFixed=false (defaultAmountInCents=null). O pagador informa o valor no app do banco antes de confirmar.
minAmountInCents / maxAmountInCents — limites globais aplicados pela plataforma. Pagamentos fora dessa faixa são rejeitados pela provedora PIX.

Webhooks

deposit:paid — pagamento via QR recebido e DePix creditado na wallet associada
deposit:expired — transação iniciada via QR expirou sem confirmação

Erros

HTTP	Código	Causa
400	VALIDATION_ERROR	Payload inválido, slug fora do padrão ou valor fora dos limites.
401	API_KEY_INVALID	Chave de API inválida, revogada ou expirada.
403	MISSING_SCOPE	Chave não possui o scope necessário (links e/ou read).
403	IP_NOT_ALLOWED	Chamada veio de IP fora da allowlist configurada para a chave.
404	NOT_FOUND	Slug não encontrado ou não pertence à conta autenticada.
409	IDEMPOTENCY_CONFLICT	X-DF-Idempotency-Key já usado anteriormente com payload diferente (apenas no POST).
429	RATE_LIMIT_EXCEEDED	Limite de requisições excedido. Aguarde X-RateLimit-Reset antes de tentar novamente.

Sandbox

Use uma chave dfk_test_* para testar todas as operações sem afetar produção. Para simular um pagamento via QR em sandbox: crie o QR, gere uma transação consumindo o slug e chame POST /v1/sandbox/deposit/:id/mark-paid com o id retornado.