Documentação da API

Introdução

A API da Deelo permite criar cobranças PIX, produtos, links de pagamento e saques de forma programática. Todas as respostas são em JSON. Valores monetários são sempre em CENTAVOS (ex: R$ 197,00 = 19700). A base URL é https://deelo.com.br/api/v1.

Autenticação

Todas as rotas exigem o header `x-api-key` com a sua chave de API. Crie chaves nomeadas em Dashboard → Configurações → Chaves de API (a chave completa só é exibida na criação — guarde-a com segurança). Operações financeiras (criar cobrança, produto, link, saque, estorno) exigem KYC aprovado.

curl https://deelo.com.br/api/v1/me -H "x-api-key: SUA_API_KEY"

Erros

Erros retornam status HTTP 4xx/5xx com o corpo { "error": { "code": string, "message": string } }. Códigos comuns: unauthorized (401, API key inválida), kyc_required (403, verificação pendente), account_blocked (403), invalid_request (400), insufficient_balance (400), amount_below_minimum (400), invalid_state (400), not_found (404).

Conta

Consulte os dados da sua conta, status do KYC e taxas vigentes.

GET/api/v1/me

Consultar conta

Retorna dados cadastrais, status do KYC e as taxas aplicadas à sua conta (personalizadas ou globais).

Exemplo (curl)

curl "https://deelo.com.br/api/v1/me" -H "x-api-key: SUA_API_KEY"

Resposta

{
  "id": "cms93...",
  "businessName": "Minha Loja LTDA",
  "status": "ACTIVE",
  "kycStatus": "APPROVED",
  "fees": {
    "pix": { "percent": 1.99, "fixedCents": 0, "releaseDays": 0 },
    "creditCard": { "percent": 4.99, "fixedCents": 100, "releaseDays": 14 },
    "boleto": { "percent": 2.49, "fixedCents": 349, "releaseDays": 2 },
    "withdrawal": { "feeCents": 367, "minCents": 5000 }
  }
}

GET/api/v1/balance

Consultar saldo

Saldo disponível para saque e saldo a liberar.

Exemplo (curl)

curl "https://deelo.com.br/api/v1/balance" -H "x-api-key: SUA_API_KEY"

Resposta

{ "availableCents": 779494, "pendingCents": 232374, "currency": "BRL" }

Transações (PIX)

Crie cobranças PIX e acompanhe o status. A confirmação chega via webhook (evento transaction.paid) ou consultando a transação.

POST/api/v1/transactionsrequer KYC

Criar cobrança PIX

Cria uma transação PIX e retorna o QR Code (data URL) e o código copia-e-cola.

Parâmetro	Tipo	Obrig.	Descrição
amountCents	int	sim	Valor em centavos (mínimo 100)
description	string	não	Descrição da cobrança
externalRef	string	não	Seu identificador externo (ex: id do pedido)
customer.name	string	não	Nome do cliente
customer.email	string	não	E-mail do cliente
customer.document	string	não	CPF/CNPJ do cliente
customer.phone	string	não	Telefone do cliente
customer.ip	string	não	IP do cliente (recomendado — enviado à UTMify)
utm.source / medium / campaign / content / term	string	não	Parâmetros de tracking (enviados à UTMify)
utm.src / utm.sck	string	não	Parâmetros src e sck da URL (enviados à UTMify)

Exemplo (curl)

curl -X POST "https://deelo.com.br/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{ "amountCents": 19700, "description": "Curso Tráfego Pago", "externalRef": "pedido-123", "customer": { "name": "Ana Souza", "email": "ana@email.com" }, "utm": { "source": "facebook", "campaign": "lancamento" } }'

Resposta

{
  "id": "cms94...",
  "status": "PENDING",
  "method": "PIX",
  "amountCents": 19700,
  "feeCents": 392,
  "netCents": 19308,
  "pix": { "code": "000201...", "qrCodeDataUrl": "data:image/png;base64,..." },
  "createdAt": "2026-07-31T13:00:00.000Z"
}

GET/api/v1/transactions

Listar transações

Lista transações com filtros e paginação.

Parâmetro	Tipo	Obrig.	Descrição
status	enum	não	PENDING, PAID, REFUSED, REFUNDED, CHARGEBACK, EXPIRED
method	enum	não	PIX, CREDIT_CARD, BOLETO
from / to	ISO date	não	Período de criação
limit	int	não	Máx. 100 (padrão 20)
offset	int	não	Paginação (padrão 0)

Exemplo (curl)

curl "https://deelo.com.br/api/v1/transactions" -H "x-api-key: SUA_API_KEY"

Resposta

{
  "data": [ { "id": "...", "status": "PAID", "amountCents": 19700, ... } ],
  "pagination": { "total": 71, "limit": 20, "offset": 0, "hasMore": true }
}

GET/api/v1/transactions/{id}

Consultar transação

Retorna uma transação específica, incluindo o código PIX.

Exemplo (curl)

curl "https://deelo.com.br/api/v1/transactions/{id}" -H "x-api-key: SUA_API_KEY"

Resposta

{ "id": "...", "status": "PAID", "paidAt": "2026-07-31T13:05:00.000Z", ... }

POST/api/v1/transactions/{id}/refundrequer KYC

Estornar transação

Estorna uma transação paga. O valor líquido é debitado do seu saldo.

Exemplo (curl)

curl -X POST "https://deelo.com.br/api/v1/transactions/{id}/refund" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY"

Resposta

{ "id": "...", "status": "REFUNDED", "refundedNetCents": 19308 }

Produtos

Produtos têm um checkout hospedado próprio (https://deelo.com.br/p/SLUG) com imagem, descrição e captura automática de UTMs.

GET/api/v1/products

Listar produtos

Lista seus produtos com a URL de checkout.

Exemplo (curl)

curl "https://deelo.com.br/api/v1/products" -H "x-api-key: SUA_API_KEY"

Resposta

{ "data": [ { "id": "...", "name": "Curso X", "priceCents": 19700, "checkoutUrl": "https://deelo.com.br/p/curso-x-ab12c", "active": true } ] }

POST/api/v1/productsrequer KYC

Criar produto

Cria um produto com checkout hospedado.

Parâmetro	Tipo	Obrig.	Descrição
name	string	sim	Nome do produto
description	string	não	Descrição exibida no checkout
priceCents	int	sim	Preço em centavos
imageUrl	string	não	URL da imagem de capa
methods	array	não	["PIX"] e/ou ["CREDIT_CARD"] (padrão ["PIX"])

Exemplo (curl)

curl -X POST "https://deelo.com.br/api/v1/products" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{ "name": "Curso Tráfego Pago", "priceCents": 19700, "methods": ["PIX", "CREDIT_CARD"] }'

Resposta

{ "id": "...", "slug": "curso-trafego-pago-x1y2z", "checkoutUrl": "https://deelo.com.br/p/curso-trafego-pago-x1y2z", ... }

Links de pagamento

Links de pagamento são checkouts simples de valor fixo (https://deelo.com.br/pay/SLUG), sem página de produto.

GET/api/v1/payment-links

Listar links

Lista seus links de pagamento.

Exemplo (curl)

curl "https://deelo.com.br/api/v1/payment-links" -H "x-api-key: SUA_API_KEY"

Resposta

{ "data": [ { "id": "...", "title": "Consultoria", "amountCents": 50000, "url": "https://deelo.com.br/pay/consultoria-ab1cd", "active": true } ] }

POST/api/v1/payment-linksrequer KYC

Criar link

Cria um link de pagamento.

Parâmetro	Tipo	Obrig.	Descrição
title	string	sim	Nome exibido no checkout
description	string	não	Descrição
amountCents	int	sim	Valor em centavos
methods	array	não	["PIX"] e/ou ["CREDIT_CARD"]

Exemplo (curl)

curl -X POST "https://deelo.com.br/api/v1/payment-links" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{ "title": "Consultoria 1h", "amountCents": 50000, "methods": ["PIX"] }'

Resposta

{ "id": "...", "slug": "consultoria-1h-ab1cd", "url": "https://deelo.com.br/pay/consultoria-1h-ab1cd", ... }

Saques

Solicite saques do saldo disponível via PIX. Saques passam por aprovação da plataforma.

GET/api/v1/withdrawals

Listar saques

Histórico de saques com status (PENDING, APPROVED, PAID, REJECTED).

Exemplo (curl)

curl "https://deelo.com.br/api/v1/withdrawals" -H "x-api-key: SUA_API_KEY"

Resposta

{ "data": [ { "id": "...", "amountCents": 150000, "feeCents": 367, "status": "PAID", "processedAt": "..." } ] }

POST/api/v1/withdrawalsrequer KYC

Solicitar saque

Cria uma solicitação de saque via PIX. O valor é debitado do saldo imediatamente.

Parâmetro	Tipo	Obrig.	Descrição
amountCents	int	sim	Valor em centavos (respeitando o mínimo)
pixKey	string	sim	Chave PIX de destino
pixKeyType	enum	sim	CPF, CNPJ, EMAIL, PHONE ou RANDOM

Exemplo (curl)

curl -X POST "https://deelo.com.br/api/v1/withdrawals" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{ "amountCents": 50000, "pixKey": "12345678900", "pixKeyType": "CPF" }'

Resposta

{ "id": "...", "amountCents": 50000, "feeCents": 367, "status": "PENDING", "createdAt": "..." }

Webhooks

Crie webhooks personalizados em Dashboard → Configurações → Webhooks, escolhendo os eventos que quer receber: transaction.created (PIX gerado), transaction.paid (compra aprovada) e transaction.refunded (reembolso). Cada webhook tem seu próprio secret. Enviamos POST JSON com os headers x-deelo-event (nome do evento) e x-deelo-signature (HMAC SHA-256 do corpo, usando o secret do webhook). Valide a assinatura antes de processar.

// Exemplo de payload (transaction.paid)
{
  "event": "transaction.paid",
  "data": {
    "id": "cms94...",
    "status": "PAID",
    "method": "PIX",
    "amountCents": 19700,
    "feeCents": 392,
    "netCents": 19308,
    "customer": { "name": "Ana Souza", "email": "ana@email.com" },
    "paidAt": "2026-07-31T13:05:00.000Z"
  }
}

// Validação em Node.js
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
const valid = expected === req.headers["x-deelo-signature"];

Integração UTMify

Com a UTMify conectada (Dashboard → Integrações), todo pedido é enviado automaticamente para a UTMify seguindo a documentação oficial: o pedido entra como waiting_payment quando o PIX é gerado e é atualizado para paid/refunded conforme o status muda. Enviamos os trackingParameters (utm_source, utm_medium, utm_campaign, utm_content, utm_term, src e sck), valores, comissões, país e IP do cliente. Nos checkouts hospedados tudo é capturado da URL automaticamente; na API, envie os campos `utm` e `customer.ip` ao criar a transação.