Enviar PIX

POST /v1/withdraw/create — criar saque DePix → PIX.

Visão geral

Cria um saque PIX usando DePix como funding. Retorna o status inicial; o envio efetivo acontece de forma assíncrona após validação anti-fraude e funding da rede Liquid.

Endpoint

POST /v1/withdraw/create

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

Autenticação

Requer scope transact, idempotência obrigatória, headers de auth completos.

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
pixKey	string	Sim	Chave PIX de destino. Consulte GET /v1/fee-rules → allowedPixKeyTypes para a lista atual de tipos aceitos.
pixKeyType	string (enum dinâmico)	Sim	Tipo da chave PIX. Valores aceitos são dinâmicos — consulte GET /v1/fee-rules → allowedPixKeyTypes.
payoutAmountCents	integer > 0	Sim	Valor em centavos a ser enviado ao destino. Inteiro positivo.
couponCode	string (≤50)	Não	Cupom opcional (≤50 chars).
taxId	string (CPF/CNPJ)	Não	CPF/CNPJ do beneficiário. Pode ser obrigatório dependendo do pixKeyType e da regra de fee ativa (GET /v1/fee-rules → requireTaxId).

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/withdraw/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 '{
    "pixKey": "12345678909",
    "pixKeyType": "cpf",
    "payoutAmountCents": 5000
  }'

Exemplo de resposta da requisição

json

{
  "data": {
    "id": "67234abc...",
    "status": "unsent",
    "pixKey": "12345678909",
    "pixKeyType": "cpf",
    "payoutAmountCents": 5000,
    "feeCents": 100,
    "depositAmountCents": 5100,
    "createdAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Status

unsent (não-terminal) — aguardando funding em DePix
sending (não-terminal) — envio em andamento
sent (terminal) — PIX enviado com sucesso
error (terminal) — falha irreversível
cancelled (terminal) — cancelado
refunded (terminal) — estornado para a conta

Webhooks

withdraw:sent — PIX foi liquidado no destino
withdraw:error — falha no envio
withdraw:cancelled — saque cancelado
withdraw:refunded — saque estornado

Erros

HTTP	Código	Causa
400	VALIDATION_ERROR	Payload inválido (chave fora do formato, valor não-inteiro, etc).
401	API_KEY_INVALID	Chave de API inválida.
403	MISSING_SCOPE	Falta scope transact.
403	TX_BLOCKED_MED	Anti-fraude MED bloqueou a transação.
403	ACCOUNT_LOCKED	Conta bloqueada (locked/banned).
409	IDEMPOTENCY_CONFLICT	X-DF-Idempotency-Key já usado com payload diferente.
429	RATE_LIMIT_EXCEEDED	Rate limit excedido.

Sandbox

Em sandbox, use POST /v1/sandbox/withdraw/:id/simulate-funds para simular o funding e progressão de status.

Configurações sujeitas a alteração

Algumas regras de envio (limites, validações extras de titularidade, gatilhos anti-fraude) podem variar por conta e ao longo do tempo. Trate respostas 4xx como definitivas e exiba mensagens retornadas ao usuário.