Payment Link — vender produtos e serviços

Ferramenta recomendada para e-commerce, infoprodutos, venda de serviços, checkout. Gere uma URL fixa por produto/oferta e compartilhe no site, redes sociais ou mensagem. Cada pagamento gera webhook. Para cobrança PIX avulsa de valor variável, use QR PIX dinâmico.

Receber por Link

POST /v1/links/create — gere URL compartilhável de pagamento.

Visão geral

Cria um payment link reutilizável com valor fixo e slug. Compartilhe a URL pública para receber pagamentos sem chamar a API a cada cobrança.

Endpoint

POST /v1/links/create

Alias deprecado: /v1/pix/links

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

Autenticação

Requer scope links. Headers Authorization, X-DF-Secret, X-DF-Passphrase e X-DF-Idempotency-Key.

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
title	string (3-100)	Sim	Título do produto/serviço (3-100 chars).
description	string (≤500)	Não	Descrição opcional (≤500 chars).
priceCents	integer > 0	Sim	Preço em centavos. Inteiro positivo.
imageUrl	url (≤2048)	Não	URL de imagem do produto (http/https, ≤2048 chars).
walletId	string (24-hex)	Não	Wallet Liquid de destino (24-hex). Default: wallet primária.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/v1/links/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 '{
    "title": "Camiseta DePix",
    "description": "Coleção 2026",
    "priceCents": 9990,
    "imageUrl": "https://cdn.exemplo.com/produto.jpg"
  }'

Exemplo de resposta da requisição

json

{
  "data": {
    "id": "67234abc...",
    "slug": "camiseta-depix-7f3a",
    "title": "Camiseta DePix",
    "description": "Coleção 2026",
    "priceCents": 9990,
    "url": "https://deflow.exchange/p/camiseta-depix-7f3a",
    "status": "active",
    "createdAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Status

active (não-terminal) — link ativo aceitando pagamentos
inactive (não-terminal) — link desativado pelo dono
expired (terminal) — link expirou
cancelled (terminal) — link cancelado permanentemente

Webhooks

deposit:paid — pagamento via link recebido e DePix creditado
deposit:expired — transação via link expirou

Erros

HTTP	Código	Causa
400	VALIDATION_ERROR	Payload inválido.
401	API_KEY_INVALID	Chave inválida.
403	MISSING_SCOPE	Falta scope links.
409	IDEMPOTENCY_CONFLICT	Idempotency key conflitando.
429	RATE_LIMIT_EXCEEDED	Rate limit excedido.

Sandbox

Em sandbox, gere o link e simule pagamento via /v1/sandbox/deposit/:id/mark-paid usando o id retornado.