⚠️ POST /v1/deposit/create temporariamente bloqueado

Endpoint indisponível no momento, retorna HTTP 503.

Para criar cobranças PIX:

POST /v1/qr/create

QR PIX dinâmico, aceita valor opcional via defaultAmountInCents.

Para vender produtos ou serviços:

POST /v1/links/create

Payment Link, ideal para e-commerce, infoproduto e checkout.

Receber Direto

POST /v1/deposit/create — crie depósitos com valor por requisição.

Visão geral

Endpoint para criar um depósito DePix único. Retorna QR PIX que o pagador escaneia ou copia/cola no app do banco. Após pagamento, o DePix é creditado na wallet Liquid configurada.

Endpoint

POST /v1/deposit/create

Scope: transact
Rate limit: 3 req/min, burst 1/5s (BLOQUEADO — retorna 503)
Idempotência obrigatória (X-DF-Idempotency-Key UUID v4)

Autenticação

Requer chave de API com scope transact. Headers Authorization, X-DF-Secret e X-DF-Passphrase são obrigatórios. X-DF-Idempotency-Key é obrigatório.

Headers

Header	Exemplo	Obrigatório
Authorization	Bearer dfk_live_...	Sim
X-DF-Secret	sk_...	Sim
X-DF-Passphrase	...	Sim
Content-Type	application/json	Sim
X-DF-Idempotency-Key	uuid-v4	Não

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
amountCents	integer	Sim	Valor em centavos. Inteiro positivo dentro de Number.MAX_SAFE_INTEGER.
mode	"exact" \| "net"	Sim	exact = pagador paga valor cheio (taxa deduzida do crédito); net = pagador paga extra para garantir crédito líquido.
walletId	string (24-hex)	Não	ID Mongo (24-hex) de wallet própria. Se omitido, usa wallet default da conta.
couponCode	string (≤50)	Não	Código de cupom opcional. Inválido é silenciosamente ignorado.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/deposit/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 '{
    "amountCents": 10000,
    "mode": "exact",
    "walletId": "65f2ab3c1d4e5f6a7b8c9d0e",
    "couponCode": "WELCOME10"
  }'

Exemplo de resposta da requisição

json

{
  "data": {
    "id": "67234abc1d4e5f6a7b8c9d0e",
    "status": "pending",
    "amountCents": 10000,
    "feeCents": 200,
    "netAmountCents": 9800,
    "mode": "exact",
    "qrCopyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
    "qrImageUrl": "https://cdn.deflow.exchange/qr/67234abc.png",
    "expiresAt": "2026-05-15T12:30:00.000Z",
    "createdAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Status

pending (não-terminal) — aguardando pagamento PIX
pending_pix2fa (não-terminal) — aguardando 2FA no banco do pagador
under_review (não-terminal) — em revisão anti-fraude
delayed (não-terminal) — atrasado mas ainda válido
depix_sent (terminal) — DePix creditado com sucesso
expired (terminal) — QR expirou sem pagamento
canceled (terminal) — cancelado manualmente
refunded (terminal) — estornado (pagamento recebido mas devolvido)
error (terminal) — erro irreversível

Webhooks

deposit:paid — depósito pago e DePix creditado
deposit:expired — QR expirou sem pagamento
deposit:canceled — depósito cancelado
deposit:error — erro irreversível
deposit:delayed — depósito atrasado mas ainda válido
deposit:under_review — depósito em revisão anti-fraude

Erros

HTTP	Código	Causa
400	VALIDATION_ERROR	Payload inválido (campos faltando, tipos errados, fora dos limites).
401	API_KEY_INVALID	Chave de API inválida, revogada ou expirada.
403	MISSING_SCOPE	Chave não possui o scope transact.
403	TX_BLOCKED_MED	Bloqueio anti-fraude MED ativo na conta.
403	FIRST_DEPOSIT_CAP	Primeiro depósito excede o cap configurado.
409	IDEMPOTENCY_CONFLICT	X-DF-Idempotency-Key já usado com payload diferente.
429	RATE_LIMIT_EXCEEDED	Limite de requisições excedido. Tente após X-RateLimit-Reset.

Sandbox

Em sandbox, use POST /v1/sandbox/deposit/:id/mark-paid para simular pagamento e disparar webhook deposit:paid.