API Reference

A depix.casa fornece uma API REST para conversão PIX → DEPIX (depósito) e DEPIX → PIX (saque). Todas as respostas são JSON. Valores monetários são sempre em centavos (inteiros).

🔗 Base URL: https://depix.casa

Convenções

Campo	Regra
Content-Type	Sempre `application/json` em requisições com body
Valores monetários	Inteiros em centavos — R$ 100,00 → `10000`
Documentos	Somente dígitos, sem pontuação — CPF: `12345678901`
Datas	ISO 8601 UTC — ex: `2026-06-16T21:00:00.000Z`

Rate Limiting

Limite padrão: 100 req/min por IP. Ao exceder, a API retorna 429. O header Retry-After indica quando tentar novamente.

Autenticação

Todas as rotas exigem uma API Key no header de autorização Bearer.

Header

Authorization: Bearer SEU_API_KEY

⚠️ Nunca exponha sua API Key no frontend ou em repositórios públicos. Armazene em variáveis de ambiente no servidor.

Para obter uma API Key, solicite acesso. O administrador gerará uma chave específica para sua integração.

Criar depósito

Gera um QR Code PIX que, ao ser pago, converte os reais para DEPIX. A taxa de 1,5% é deduzida automaticamente do valor recebido.

POST /v1/deposits

Body

Campo	Tipo	Descrição
amountInCentsobrigatório	integer	Valor em centavos. Mínimo: `100` (R$ 1,00)
customerDocumentobrigatório	string	CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, somente números
externalRefopcional	string	ID do seu sistema para rastreamento. Máx. 200 caracteres
depixAddressopcional	string	Endereço Liquid/DEPIX para recebimento. Se omitido, usa o endereço padrão da conta

Exemplo — cURL

cURL

curl -X POST https://depix.casa/v1/deposits \
  -H "Authorization: Bearer SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 10000,
    "customerDocument": "12345678901",
    "externalRef": "pedido-42",
    "depixAddress": "ex1q..."
  }'

Exemplo — Node.js

Node.js

const res = await fetch('https://depix.casa/v1/deposits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amountInCents: 10000,
    customerDocument: '12345678901',
    externalRef: 'pedido-42',
    depixAddress: 'ex1q...', // opcional
  }),
});
const deposit = await res.json();
// exibir deposit.qrCopyPaste ou deposit.qrImageUrl

Resposta 201 Created

JSON

{
  "id": "d3e4f5a6-b1c2-4d3e-8f9a-0b1c2d3e4f5a",
  "providerTxid": "txid_abc123def456",
  "grossAmount": 10000,
  "feeAmount": 150,
  "netAmount": 9850,
  "status": "PENDING",
  "qrCopyPaste": "00020126580014br.gov.bcb.pix0136...",
  "qrImageUrl": "https://api.eulen.io/qr/txid_abc123def456.png",
  "externalRef": "pedido-42",
  "createdAt": "2026-06-16T21:00:00.000Z"
}

💡 Apresente qrCopyPaste (Pix Copia e Cola) ou qrImageUrl ao usuário. O depósito é confirmado via webhook DEPOSIT_COMPLETED — não faça polling.

Buscar depósito

Retorna os dados de um depósito pelo providerTxid recebido na criação.

GET /v1/deposits/:providerTxid

cURL

curl https://depix.casa/v1/deposits/txid_abc123def456 \
  -H "Authorization: Bearer SEU_API_KEY"

Resposta 200 OK

JSON

{
  "id": "d3e4f5a6-b1c2-4d3e-8f9a-0b1c2d3e4f5a",
  "providerTxid": "txid_abc123def456",
  "grossAmount": 10000,
  "feeAmount": 150,
  "netAmount": 9850,
  "status": "COMPLETED",
  "payerName": "João Silva",
  "payerTaxNumber": "12345678901",
  "externalRef": "pedido-42",
  "createdAt": "2026-06-16T21:00:00.000Z",
  "updatedAt": "2026-06-16T21:04:00.000Z"
}

Status possíveis

Status	Significado
PENDING	QR Code gerado, aguardando pagamento
CONFIRMED	Pagamento recebido, conversão em andamento
COMPLETED	DEPIX creditado com sucesso
FAILED	Falha no processamento
EXPIRED	QR Code expirado sem pagamento

Listar depósitos

Retorna lista paginada dos depósitos da sua conta, com filtros opcionais.

GET /v1/deposits

Query params

Campo	Tipo	Descrição
statusopcional	string	`PENDING` \| `CONFIRMED` \| `COMPLETED` \| `FAILED` \| `EXPIRED`
startDateopcional	string	Data inicial ISO 8601. Ex: `2026-06-01T00:00:00.000Z`
endDateopcional	string	Data final ISO 8601
pageopcional	integer	Página. Default: `1`
limitopcional	integer	Itens por página, máx. 100. Default: `20`

cURL

curl "https://depix.casa/v1/deposits?status=COMPLETED&page=1&limit=20" \
  -H "Authorization: Bearer SEU_API_KEY"

Resposta 200 OK

JSON

{
  "deposits": [
    {
      "id": "d3e4f5a6-...",
      "providerTxid": "txid_abc123def456",
      "grossAmount": 10000,
      "feeAmount": 150,
      "netAmount": 9850,
      "status": "COMPLETED",
      "externalRef": "pedido-42",
      "createdAt": "2026-06-16T21:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Criar saque

Converte DEPIX para PIX, enviando reais para uma chave Pix do beneficiário. Prazo de liquidação: até D+2 (48h).

POST /v1/withdrawals

Body

Campo	Tipo	Descrição
pixKeyobrigatório	string	Chave Pix do beneficiário (CPF, e-mail, telefone, chave aleatória)
amountInCentsobrigatório	integer	Valor em centavos de DEPIX a converter. Mínimo: `100`
taxNumberobrigatório	string	CPF ou CNPJ do beneficiário (somente dígitos)
externalRefopcional	string	ID do seu sistema. Máx. 200 caracteres

Exemplo — cURL

cURL

curl -X POST https://depix.casa/v1/withdrawals \
  -H "Authorization: Bearer SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "joao@email.com",
    "amountInCents": 5000,
    "taxNumber": "12345678901",
    "externalRef": "saque-10"
  }'

Exemplo — Node.js

Node.js

const res = await fetch('https://depix.casa/v1/withdrawals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pixKey: 'joao@email.com',
    amountInCents: 5000,
    taxNumber: '12345678901',
    externalRef: 'saque-10',
  }),
});
const saque = await res.json();

Resposta 201 Created

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "pixKey": "joao@email.com",
  "depositAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "depositAmountInCents": 5000,
  "payoutAmountInCents": 4925,
  "feeAmount": 75,
  "externalRef": "saque-10",
  "createdAt": "2026-06-16T21:00:00.000Z"
}

💡 depositAddress é o endereço DEPIX que deve receber o valor. O pagamento em reais é processado em até D+2. Acompanhe via webhook WITHDRAW_COMPLETED.

Buscar saque

Retorna os dados de um saque pelo seu id.

GET /v1/withdrawals/:id

cURL

curl https://depix.casa/v1/withdrawals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer SEU_API_KEY"

Status possíveis

Status	Significado
PENDING	Aguardando início do processamento
PROCESSING	Em processamento pelo provedor
COMPLETED	Pix enviado ao beneficiário
FAILED	Falha — verifique a chave Pix informada

Listar saques

GET /v1/withdrawals

Query params

Campo	Tipo	Descrição
statusopcional	string	`PENDING` \| `PROCESSING` \| `COMPLETED` \| `FAILED`
startDateopcional	string	Data inicial ISO 8601
endDateopcional	string	Data final ISO 8601
pageopcional	integer	Default: `1`
limitopcional	integer	Máx. 100. Default: `20`

cURL

curl "https://depix.casa/v1/withdrawals?status=COMPLETED&limit=10" \
  -H "Authorization: Bearer SEU_API_KEY"

Eventos de Webhook

Configure uma webhookUrl ao se cadastrar. A API enviará um POST para essa URL sempre que houver atualização de status.

Eventos disponíveis

Evento	Quando ocorre
DEPOSIT_CONFIRMED	Pagamento PIX recebido pelo provedor
DEPOSIT_COMPLETED	DEPIX creditado com sucesso
DEPOSIT_FAILED	Falha no processamento do depósito
WITHDRAW_CREATED	Saque criado e aceito
WITHDRAW_COMPLETED	Pix enviado ao beneficiário
WITHDRAW_FAILED	Falha no envio do Pix

Payload

JSON

{
  "event": "DEPOSIT_COMPLETED",
  "timestamp": "2026-06-16T21:05:00.000Z",
  "data": {
    "id": "d3e4f5a6-b1c2-4d3e-8f9a-0b1c2d3e4f5a",
    "providerTxid": "txid_abc123def456",
    "grossAmount": 10000,
    "feeAmount": 150,
    "netAmount": 9850,
    "status": "COMPLETED",
    "externalRef": "pedido-42"
  }
}

Verificação HMAC

Cada webhook inclui o header X-Depix-Signature: sha256=<hex> gerado com HMAC-SHA256 do body raw usando seu webhookSecret. Sempre valide a assinatura antes de processar.

Node.js

import crypto from 'crypto';

function verifyWebhook(rawBody: Buffer, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  // timingSafeEqual previne timing attacks
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

// Fastify — raw body
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => {
  done(null, body);
});

fastify.post('/webhook', async (request, reply) => {
  const sig = request.headers['x-depix-signature'] as string;
  if (!verifyWebhook(request.body as Buffer, sig, process.env.WEBHOOK_SECRET!)) {
    return reply.code(401).send({ error: 'Invalid signature' });
  }
  const event = JSON.parse((request.body as Buffer).toString());
  // processar event.event e event.data
  return reply.send({ received: true });
});

Retry Policy

Em caso de timeout ou resposta HTTP fora do range 2xx, a API realiza novas tentativas com backoff exponencial:

Tentativa	Delay após falha
1ª	1 minuto
2ª	5 minutos
3ª	15 minutos
4ª	1 hora
5ª	6 horas

Após 5 falhas consecutivas o evento é marcado como FAILED. Seu endpoint deve responder em até 30 segundos. Retorne qualquer status 2xx para confirmar o recebimento.

Erros

A API usa códigos HTTP padrão. Todas as respostas de erro seguem o formato:

JSON

{
  "error": "Validation error",
  "details": [
    { "path": ["amountInCents"], "message": "Number must be greater than or equal to 100" }
  ]
}

Código	Significado
400	Dados inválidos — veja `details` para o campo específico
401	API Key ausente, expirada ou inválida
404	Recurso não encontrado (providerTxid ou id incorreto)
429	Rate limit excedido — aguarde e tente novamente
500	Erro interno — contate suporte se persistir

API Reference

Convenções

Rate Limiting

Autenticação

Criar depósito

Body

Exemplo — cURL

Exemplo — Node.js

Resposta 201 Created

Buscar depósito

Resposta 200 OK

Status possíveis

Listar depósitos

Query params

Resposta 200 OK

Criar saque

Body

Exemplo — cURL

Exemplo — Node.js

Resposta 201 Created

Buscar saque

Status possíveis

Listar saques

Query params

Eventos de Webhook

Eventos disponíveis

Payload

Verificação HMAC

Retry Policy

Erros

Solicitar Acesso