Documentação da API

Integração de pagamentos PIX simples e poderosa

Última atualização: 14 de Fevereiro de 2026

📖 Introdução

A DEPIX PRO API permite integrar pagamentos PIX em sua aplicação de forma rápida e segura. Nossa API RESTful utiliza JSON para comunicação e oferece webhooks para notificações em tempo real.

Principais Recursos:

• Geração instantânea de pagamentos PIX (QR Code)
• Status de pagamento em tempo real
• Notificações automáticas via webhook
• Suporte à validação de CPF/CNPJ
• Autenticação segura via API key
• Sistema progressivo de limites (7 níveis)
• Settlement em Liquid Network (L-BTC)
• Auto-cadastro de merchants via API

URL Base:

https://api.depixpay.com/api/v1

🚀 Primeiros Passos

🔐 Autenticação

Todas as requisições autenticadas requerem sua chave de API no header X-API-Key.

X-API-Key: dpx_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

👤 Merchant (Cadastro)

{
  "name": "Minha Loja",
  "liquid_address": "lq1qq...",
  "webhook_url": "https://meusite.com/webhook/depix"
}

{
  "success": true,
  "message": "Merchant registered successfully. Save your API key - it will not be shown again.",
  "data": {
    "id": "cfd766d2-1f32-45f5-b3c4-1e236d57b1c1",
    "name": "Minha Loja",
    "liquid_address": "lq1qq...",
    "webhook_url": "https://meusite.com/webhook/depix",
    "level": 1,
    "level_name": "Beginner",
    "current_limit": 500,
    "total_confirmed": 0,
    "is_active": true,
    "created_at": "2026-01-15T12:00:00.000Z",
    "api_key": "dpx_f4feedc1b1c526c050d78c42c296e2e..."
  }
}

{
  "success": true,
  "data": {
    "id": "cfd766d2-...",
    "name": "Minha Loja",
    "liquid_address": "lq1qq...",
    "webhook_url": "https://meusite.com/webhook/depix",
    "level": 3,
    "level_name": "Silver",
    "current_limit": 1000,
    "total_confirmed": 750.50,
    "is_active": true,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}

{
  "name": "Novo Nome",
  "liquid_address": "lq1qq_novo_endereco...",
  "webhook_url": "https://novo-site.com/webhook"
}

💳 Pagamentos

{
  "amount": 25.50,
  "description": "Produto XYZ",
  "customer_name": "João Silva",
  "customer_cpf": "12345678901",
  "customer_email": "[email protected]",
  "customer_phone": "(11) 99999-9999",
  "customer_address": "Rua das Flores, 123, Centro, São Paulo, SP",
  "external_id": "pedido_123",
  "webhook_url": "https://seusite.com/webhook"
}

{
  "success": true,
  "data": {
    "payment_id": "dep_abc123def456ghij",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_image_url": "https://response.eulen.app/api-response/...-qr.png",
    "expires_at": "2026-01-15T12:20:00.000Z",
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": "LIMIT_EXCEEDED",
  "message": "Valor excede seu limite atual de R$ 500,00",
  "current_limit": 500.00,
  "amount_requested": 500.00
}

{
  "success": true,
  "data": {
    "payment_id": "dep_abc123def456ghij",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "completed",
    "customer_name": "João Silva",
    "customer_cpf": "12345678901",
    "customer_phone": "(11) 99999-9999",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:15:30.000Z"
  }
}

{
  "success": true,
  "data": {
    "payment_id": "dep_abc123def456ghij",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "completed",
    "customer_name": "João Silva",
    "customer_cpf": "12345678901",
    "customer_email": "[email protected]",
    "customer_phone": "(11) 99999-9999",
    "customer_address": "Rua das Flores, 123",
    "description": "Produto XYZ",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_image_url": "https://response.eulen.app/...-qr.png",
    "expires_at": "2026-01-15T12:20:00.000Z",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:15:30.000Z"
  }
}

Status de Pagamento:

🔔 Webhooks

Os webhooks permitem que sua aplicação receba notificações automáticas em tempo real quando o status de um pagamento muda.

Configuração

Defina a webhook_url no cadastro do merchant (padrão) ou ao criar cada pagamento (override).

Requisitos do Endpoint

• Seu endpoint deve aceitar requisições POST
• Responda com HTTP 200-299 para confirmar recebimento
• Timeout: 10 segundos por tentativa
• Recomendamos usar HTTPS para segurança

Eventos Disponíveis

Headers da Requisição

Content-Type: application/json
X-Webhook-Event: payment.completed
X-Webhook-Timestamp: 1705328130
User-Agent: DepixPro-Webhook/1.0

Payload: payment.completed

{
  "event": "payment.completed",
  "timestamp": "2026-01-15T12:15:30-03:00",
  "data": {
    "payment_id": "dep_abc123def456ghij",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "completed",
    "payer_name": "João Silva",
    "payer_cpf": "12345678901",
    "description": "Produto XYZ",
    "created_at": "2026-01-15 12:00:00",
    "completed_at": "2026-01-15 12:15:30"
  }
}

Payload: payment.expired

{
  "event": "payment.expired",
  "timestamp": "2026-01-15T12:20:00-03:00",
  "data": {
    "payment_id": "dep_abc123def456ghij",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "expired",
    "created_at": "2026-01-15 12:00:00",
    "expired_at": "2026-01-15 12:20:00"
  }
}

📊 Sistema de Progressão de Limites

Os limites evoluem em 7 níveis conforme seu histórico de transações confirmadas.

💰 Taxas

💻 Exemplos de Código

1. Registrar Merchant

cURL:

curl -X POST https://api.depixpay.com/api/v1/merchant/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha Loja",
    "liquid_address": "lq1qqyour_liquid_address_here",
    "webhook_url": "https://meusite.com/webhook/depix"
  }'

# ⚠️ SALVE O api_key DA RESPOSTA!

2. Criar Pagamento

JavaScript / Node.js:

const response = await fetch('https://api.depixpay.com/api/v1/payment/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'dpx_your_api_key_here'
  },
  body: JSON.stringify({
    amount: 25.50,
    description: 'Produto XYZ',
    customer_name: 'João Silva',
    customer_cpf: '12345678901',
    external_id: 'pedido_123'
  })
});

const data = await response.json();

if (data.success) {
  console.log('Payment ID:', data.data.payment_id);
  console.log('PIX Copia e Cola:', data.data.qr_code);
  console.log('QR Image:', data.data.qr_image_url);
  console.log('Expira em:', data.data.expires_at);
}

PHP:

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.depixpay.com/api/v1/payment/create',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: dpx_your_api_key_here'
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 25.50,
    'description' => 'Produto XYZ',
    'customer_name' => 'João Silva',
    'customer_cpf' => '12345678901',
    'external_id' => 'pedido_123'
  ])
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 201) {
  $data = json_decode($response, true);
  echo "Payment ID: " . $data['data']['payment_id'] . "\n";
  echo "QR Code URL: " . $data['data']['qr_image_url'] . "\n";
} else {
  echo "Erro: " . $response;
}

Python:

import requests

response = requests.post(
    'https://api.depixpay.com/api/v1/payment/create',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'dpx_your_api_key_here'
    },
    json={
        'amount': 25.50,
        'description': 'Produto XYZ',
        'customer_name': 'João Silva',
        'customer_cpf': '12345678901',
        'external_id': 'pedido_123'
    }
)

data = response.json()
if data['success']:
    print(f"Payment ID: {data['data']['payment_id']}")
    print(f"QR Code: {data['data']['qr_image_url']}")
else:
    print(f"Erro: {data['error']} - {data['message']}")

3. Consultar Status

curl https://api.depixpay.com/api/v1/payment/dep_abc123/status \
  -H "X-API-Key: dpx_your_api_key_here"

4. Webhook Handler (PHP)

<?php
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

if (!$data || !isset($data['event'])) {
  http_response_code(400);
  exit('Invalid payload');
}

switch ($data['event']) {
  case 'payment.completed':
    $paymentId = $data['data']['payment_id'];
    $amount = $data['data']['amount'];
    $externalId = $data['data']['external_id'];
    
    // Atualizar pedido no seu banco de dados
    // marcarPedidoComoPago($externalId);
    
    error_log("Pagamento {$paymentId} confirmado: R\$ {$amount}");
    break;

  case 'payment.expired':
    // Cancelar pedido
    // cancelarPedido($data['data']['external_id']);
    error_log("Pagamento {$data['data']['payment_id']} expirou");
    break;

  case 'payment.refunded':
    // Processar reembolso
    error_log("Pagamento {$data['data']['payment_id']} reembolsado");
    break;
}

http_response_code(200);
echo json_encode(['received' => true]);

5. Webhook Handler (Node.js / Express)

app.post('/webhook/depix', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'payment.completed':
      console.log(`Pagamento ${data.payment_id} confirmado: R$ ${data.amount}`);
      // Atualizar pedido no banco
      break;
    case 'payment.expired':
      console.log(`Pagamento ${data.payment_id} expirou`);
      // Cancelar pedido
      break;
    case 'payment.refunded':
      console.log(`Pagamento ${data.payment_id} reembolsado`);
      break;
  }

  res.json({ received: true });
});

⚠️ Códigos de Erro

⏰ Expiração

Todos os pagamentos PIX expiram automaticamente em 20 minutos após a criação. Recomendamos consultar o status a cada 30 segundos enquanto aguarda pagamento.