Documentação da API

Bem-vindo à documentação da API Blackcat. Aqui você encontrará tudo que precisa para integrar pagamentos PIX, Cartão de Crédito e Boleto em sua aplicação.

Base URL

Produção
https://api.blackcatpagamentos.online/api

Formato

Todas as requisições e respostas utilizam o formato JSON. Certifique-se de incluir o header:

Content-Type: application/json

Valores Monetários

⚠️
Importante: Todos os valores monetários são em centavos. Por exemplo, R$ 99,90 deve ser enviado como 9990.

Autenticação

A API utiliza autenticação via API Key. Você pode obter sua API Key no painel administrativo.

Header de Autenticação

Inclua sua API Key em todas as requisições:

Header
X-API-Key: sua_api_key_aqui

Exemplo de Requisição

cURL
curl -X POST https://api.blackcatpagamentos.online/api/sales/create-sale \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{"amount": 9990, "paymentMethod": "PIX", ...}'

Criar Venda

Cria uma nova transação de pagamento via PIX.

POST /sales/create-sale

Parâmetros do Body

Campo Tipo Obrigatório Descrição
amount integer Sim Valor em centavos. Ex: 1000 = R$ 10,00
currency string Não Moeda da transação. Default: BRL
paymentMethod string Sim pix
items array Sim Lista de itens da venda (mínimo 1 item)
customer object Sim Dados do cliente (ver abaixo)
pix object Não Configurações específicas para PIX
shipping object Condicional Endereço de entrega (obrigatório quando há produtos com tangible: true)
metadata string Não Informações adicionais sobre a venda
postbackUrl string Não URL para receber notificações de webhook sobre mudanças de status
externalRef string Não Seu identificador único para esta venda
utm_source string Não Origem do tráfego (google, facebook, email, etc.)
utm_medium string Não Meio de marketing (cpc, email, social, etc.)
utm_campaign string Não Nome da campanha de marketing
utm_content string Não Conteúdo específico do anúncio
utm_term string Não Termo de pesquisa associado

Objeto Items

Campo Tipo Obrigatório Descrição
title string Sim Nome/descrição do item
unitPrice integer Sim Preço unitário em centavos. Ex: 10000 = R$ 100,00
quantity integer Sim Quantidade do item
tangible boolean Não Se é um produto físico (true) ou digital (false). Default: false

Objeto Customer

Campo Tipo Obrigatório Descrição
name string Sim Nome completo do cliente
email string Sim E-mail do cliente
phone string Sim Telefone (apenas números)
document object Sim Documento do cliente

Objeto Document

Campo Tipo Obrigatório Descrição
number string Sim Número do documento (apenas números)
type string Sim cpf ou cnpj

Objeto PIX

Campo Tipo Obrigatório Descrição
expiresInDays integer Não Dias para expiração do PIX. Default: 1

Objeto Shipping (Produtos Físicos)

⚠️ Obrigatório para produtos físicos: Quando algum item tiver tangible: true, o objeto shipping se torna obrigatório.
Campo Tipo Obrigatório Descrição
name string Sim* Nome do destinatário para entrega
street string Sim* Rua/Logradouro do endereço de entrega
number string Sim* Número do endereço
complement string Não Complemento (apto, bloco, etc.)
neighborhood string Sim* Bairro
city string Sim* Cidade
state string Sim* Estado (UF) - 2 caracteres. Ex: SP, RJ
zipCode string Sim* CEP (apenas números)

* Obrigatório apenas quando há produtos com tangible: true

📊 Campos UTM para Analytics

📈 Rastreamento de Campanhas: Use os campos UTM para rastrear a origem das suas vendas e medir o ROI das suas campanhas de marketing.

Todos os campos UTM são opcionais e serão armazenados no metadata da transação:

Campo Descrição Exemplo
utm_source Origem do tráfego google, facebook, email, newsletter
utm_medium Meio de marketing cpc, email, social, banner
utm_campaign Nome da campanha black_friday_2024, lancamento_produto
utm_content Conteúdo específico banner_principal, video_demo
utm_term Termo de pesquisa curso_javascript, pagamento_pix
💾 Armazenamento: Os dados UTM ficam em transaction.metadata.utm e são preservados junto com outros metadados existentes.

Exemplos de Código

💡 Dica: Os exemplos abaixo mostram uma venda de produto digital. Para produtos físicos (tangible: true), você deve adicionar o objeto shipping com todos os campos de endereço (name, street, number, neighborhood, city, state, zipCode).
cURL
curl -X POST "https://api.blackcatpagamentos.online/api/sales/create-sale" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "paymentMethod": "pix",
    "items": [
      {
        "title": "Curso de JavaScript Avançado",
        "quantity": 1,
        "tangible": false
      }
    ],
    "customer": {
      "name": "João da Silva",
      "email": "joao@email.com",
      "phone": "11999999999",
      "document": {
        "number": "12345678901",
        "type": "cpf"
      }
    },
    "pix": {
      "expiresInDays": 2
    },
    "postbackUrl": "https://meusite.com/webhook/payment",
    "metadata": "Primeira compra do cliente",
    "externalRef": "ORDER-2024-001",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "lancamento_2024",
    "utm_content": "banner_home",
    "utm_term": "curso_javascript"
  }'
TypeScript
interface CreateSaleRequest {
  amount: number;
  currency: string;
  paymentMethod: string;
  items: Array<{
    title: string;
    quantity: number;
    tangible: boolean;
  }>;
  customer: {
    name: string;
    email: string;
    phone: string;
    document: {
      number: string;
      type: 'cpf' | 'cnpj';
    };
  };
  pix?: {
    expiresInDays: number;
  };
  postbackUrl?: string;
  metadata?: string;
  externalRef?: string;
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_content?: string;
  utm_term?: string;
}

async function createSale(apiKey: string, data: CreateSaleRequest) {
  const response = await fetch('https://api.blackcatpagamentos.online/api/sales/create-sale', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify(data)
  });

  return response.json();
}

// Exemplo de uso
const sale = await createSale('sua_api_key_aqui', {
  amount: 1000,
  currency: 'BRL',
  paymentMethod: 'pix',
  items: [
    {
      title: 'Curso de JavaScript Avançado',
      quantity: 1,
      tangible: false
    }
  ],
  customer: {
    name: 'João da Silva',
    email: 'joao@email.com',
    phone: '11999999999',
    document: {
      number: '12345678901',
      type: 'cpf'
    }
  },
  pix: {
    expiresInDays: 2
  },
  metadata: 'Primeira compra do cliente',
  postbackUrl: 'https://meusite.com/webhook/payment',
  externalRef: 'ORDER-2024-001',
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'lancamento_2024',
  utm_content: 'banner_home',
  utm_term: 'curso_javascript'
});

console.log(sale);
JavaScript
async function createSale(apiKey, data) {
  const response = await fetch('https://api.blackcatpagamentos.online/api/sales/create-sale', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify(data)
  });

  return response.json();
}

// Exemplo de uso
const sale = await createSale('sua_api_key_aqui', {
  amount: 1000,
  currency: 'BRL',
  paymentMethod: 'pix',
  items: [
    {
      title: 'Curso de JavaScript Avançado',
      quantity: 1,
      tangible: false
    }
  ],
  customer: {
    name: 'João da Silva',
    email: 'joao@email.com',
    phone: '11999999999',
    document: {
      number: '12345678901',
      type: 'cpf'
    }
  },
  pix: {
    expiresInDays: 2
  },
  postbackUrl: 'https://meusite.com/webhook/payment',
  metadata: 'Primeira compra do cliente',
  externalRef: 'ORDER-2024-001',
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'lancamento_2024',
  utm_content: 'banner_home',
  utm_term: 'curso_javascript'
});

console.log(sale);
PHP
<?php

function createSale($apiKey, $data) {
    $ch = curl_init();
    
    curl_setopt_array($ch, [
        CURLOPT_URL => 'https://api.blackcatpagamentos.online/api/sales/create-sale',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $apiKey
        ]
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Exemplo de uso
$sale = createSale('sua_api_key_aqui', [
    'amount' => 1000,
    'currency' => 'BRL',
    'paymentMethod' => 'pix',
    'items' => [
        [
            'title' => 'Curso de JavaScript Avançado',
            'quantity' => 1,
            'tangible' => false
        ]
    ],
    'customer' => [
        'name' => 'João da Silva',
        'email' => 'joao@email.com',
        'phone' => '11999999999',
        'document' => [
            'number' => '12345678901',
            'type' => 'cpf'
        ]
    ],
    'pix' => [
        'expiresInDays' => 2
    ],
    'postbackUrl' => 'https://meusite.com/webhook/payment',
    'metadata' => 'Primeira compra do cliente',
    'externalRef' => 'ORDER-2024-001',
    'utm_source' => 'google',
    'utm_medium' => 'cpc',
    'utm_campaign' => 'lancamento_2024',
    'utm_content' => 'banner_home',
    'utm_term' => 'curso_javascript'
]);

print_r($sale);

📦 Exemplo com Produto Físico

Quando algum item tiver tangible: true, é obrigatório enviar os dados de endereço no campo shipping:

Produto Físico com Endereço de Entrega
curl -X POST "https://api.blackcatpagamentos.online/api/sales/create-sale" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "amount": 15000,
    "currency": "BRL",
    "paymentMethod": "pix",
    "items": [
      {
        "title": "Camiseta Personalizada",
        "unitPrice": 12000,
        "quantity": 1,
        "tangible": true
      },
      {
        "title": "Frete Correios",
        "unitPrice": 3000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "customer": {
      "name": "Carlos Oliveira",
      "email": "carlos@email.com",
      "phone": "11988887777",
      "document": {
        "number": "12345678901",
        "type": "cpf"
      }
    },
    "shipping": {
      "name": "Carlos Oliveira",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 45",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01234567"
    },
    "pix": {
      "expiresInDays": 2
    },
    "postbackUrl": "https://meusite.com/webhook/payment",
    "externalRef": "ORDER-2024-002",
    "utm_source": "facebook",
    "utm_medium": "social",
    "utm_campaign": "produtos_fisicos_2024"
  }'

Response - 201 Created

Sucesso
{
  "success": true,
  "data": {
    "transactionId": "TXN-1733654321-ABC123",
    "status": "PENDING",
    "paymentMethod": "pix",
    "amount": 1000,
    "netAmount": 970,
    "fees": 30,
    "invoiceUrl": "https://blackcat.squarify.co/checkout/TXN-1733654321-ABC123",
    "createdAt": "2025-12-08T10:30:00.000Z",
    "paymentData": {
      "qrCode": "00020126580014br.gov.bcb.pix...",
      "qrCodeBase64": "data:image/png;base64,...",
      "copyPaste": "00020126580014br.gov.bcb.pix...",
      "expiresAt": "2025-12-10T10:30:00.000Z"
    }
  }
}

Campos da Resposta

Campo Tipo Descrição
transactionId string ID único da transação
status string Status da transação: PENDING, PAID, CANCELLED
paymentMethod string Método de pagamento utilizado
amount integer Valor bruto em centavos
netAmount integer Valor líquido em centavos (após taxas)
fees integer Taxas cobradas em centavos
invoiceUrl string URL para visualização da fatura pelo cliente
paymentData object Dados específicos do método de pagamento (QR Code para PIX)

Response - 400 Bad Request

Erro de Validação
{
  "success": false,
  "message": "Dados inválidos",
  "error": "O campo 'items' é obrigatório e deve conter ao menos 1 item"
}

Consultar Status

Consulta o status atual de uma transação pelo ID.

GET /sales/{transactionId}/status

Parâmetros de URL

Parâmetro Tipo Descrição
transactionId string ID da transação retornado na criação

Exemplos de Código

cURL
curl -X GET "https://api.blackcatpagamentos.online/api/sales/TXN-1733654321-ABC123/status" \
  -H "X-API-Key: sua_api_key_aqui"
TypeScript
interface TransactionStatus {
  success: boolean;
  data: {
    transactionId: string;
    status: 'PENDING' | 'PAID' | 'CANCELLED' | 'REFUNDED';
    paymentMethod: string;
    amount: number;
    netAmount: number;
    fees: number;
    paidAt?: string;
    endToEndId?: string;
  };
}

async function getTransactionStatus(apiKey: string, transactionId: string): Promise<TransactionStatus> {
  const response = await fetch(
    `https://api.blackcatpagamentos.online/api/sales/${transactionId}/status`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  return response.json();
}

// Exemplo de uso
const status = await getTransactionStatus('sua_api_key_aqui', 'TXN-1733654321-ABC123');
console.log(status.data.status); // 'PAID'
JavaScript
async function getTransactionStatus(apiKey, transactionId) {
  const response = await fetch(
    `https://api.blackcatpagamentos.online/api/sales/${transactionId}/status`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  return response.json();
}

// Exemplo de uso
const status = await getTransactionStatus('sua_api_key_aqui', 'TXN-1733654321-ABC123');
console.log(status.data.status); // 'PAID'
PHP
<?php

function getTransactionStatus($apiKey, $transactionId) {
    $ch = curl_init();
    
    curl_setopt_array($ch, [
        CURLOPT_URL => "https://api.blackcatpagamentos.online/api/sales/{$transactionId}/status",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey
        ]
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Exemplo de uso
$status = getTransactionStatus('sua_api_key_aqui', 'TXN-1733654321-ABC123');
echo $status['data']['status']; // 'PAID'

Status Possíveis

Status Descrição
PENDING Aguardando pagamento
PAID Pagamento confirmado
CANCELLED Transação cancelada ou expirada
REFUNDED Pagamento estornado

Response - 200 OK

Sucesso
{
  "success": true,
  "data": {
    "transactionId": "TXN-1733654321-ABC123",
    "status": "PAID",
    "paymentMethod": "PIX",
    "amount": 1000,
    "netAmount": 970,
    "fees": 30,
    "paidAt": "2025-12-08T10:35:00.000Z",
    "endToEndId": "E12345678202312081035XYZ123"
  }
}

Dados do Vendedor

Retorna informações básicas da empresa associada à API Key, como nome, CNPJ e logo. Útil para personalizar interfaces de checkout e identificar o vendedor.

GET /sales/seller

Resposta

Campo Tipo Descrição
success boolean Indica se a requisição foi bem-sucedida
data.name string Nome fantasia da empresa
data.legalName string Razão social completa da empresa
data.cnpj string CNPJ formatado (XX.XXX.XXX/XXXX-XX)
data.logo string|null URL do logotipo da empresa (null se não configurado)

Exemplo de Resposta

Resposta JSON
{
  "success": true,
  "data": {
    "name": "Tech Store",
    "legalName": "Tech Store Comércio Ltda",
    "cnpj": "12.345.678/0001-90",
    "logo": "https://cdn.exemplo.com/logos/techstore.png"
  }
}

Exemplos de Código

cURL
curl -X GET "https://api.blackcatpagamentos.online/api/sales/seller" \
  -H "X-API-Key: sua_api_key_aqui"
TypeScript
interface SellerResponse {
  success: boolean;
  data: {
    name: string;
    legalName: string;
    cnpj: string;
    logo: string | null;
  };
}

async function getSellerInfo(): Promise {
  const response = await fetch('https://api.blackcatpagamentos.online/api/sales/seller', {
    method: 'GET',
    headers: {
      'X-API-Key': 'sua_api_key_aqui',
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Uso
getSellerInfo()
  .then(data => {
    console.log('Dados do vendedor:', data.data);
    console.log('Nome fantasia:', data.data.name);
    console.log('CNPJ:', data.data.cnpj);
  })
  .catch(error => console.error('Erro:', error));
JavaScript
async function getSellerInfo() {
  try {
    const response = await fetch('https://api.blackcatpagamentos.online/api/sales/seller', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer sua_api_key_aqui',
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    
    // Exibir informações do vendedor no checkout
    document.getElementById('seller-name').textContent = data.data.name;
    document.getElementById('seller-cnpj').textContent = data.data.cnpj;
    
    if (data.data.logo) {
      document.getElementById('seller-logo').src = data.data.logo;
    }
    
    return data;
  } catch (error) {
    console.error('Erro ao buscar dados do vendedor:', error);
    throw error;
  }
}

// Carregar dados quando a página carrega
document.addEventListener('DOMContentLoaded', () => {
  getSellerInfo();
});
PHP
 'https://api.blackcatpagamentos.online/api/sales/seller',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'Content-Type: application/json'
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    if (curl_error($ch)) {
        throw new Exception('Erro na requisição: ' . curl_error($ch));
    }
    
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("Erro HTTP: $httpCode");
    }
    
    return json_decode($response, true);
}

try {
    $apiKey = 'sua_api_key_aqui';
    $sellerData = getSellerInfo($apiKey);
    
    echo "Nome fantasia: " . $sellerData['data']['name'] . "\n";
    echo "Razão social: " . $sellerData['data']['legalName'] . "\n";
    echo "CNPJ: " . $sellerData['data']['cnpj'] . "\n";
    
    if ($sellerData['data']['logo']) {
        echo "Logo: " . $sellerData['data']['logo'] . "\n";
    }
    
} catch (Exception $e) {
    echo "Erro: " . $e->getMessage() . "\n";
}

?>
💡
Dica: Use este endpoint para personalizar a interface de checkout com os dados da sua empresa, criando uma experiência mais profissional para seus clientes.

💰 Criar Saque

Cria uma nova solicitação de saque via PIX. Permite que você retire os fundos disponíveis da sua conta.

POST /sales/create-withdrawal
🔐
Requisito: A empresa deve ter a funcionalidade de saques via API habilitada. Entre em contato com o suporte para ativar.

Parâmetros do Body

Campo Tipo Obrigatório Descrição
amount number ✅ Sim Valor do saque em reais (ex: 100.50)
pixKey string ✅ Sim Chave PIX de destino
method string ❌ Não Método de saque (padrão: "PIX")
pixKeyType string ❌ Não Tipo da chave PIX (detectado automaticamente)
description string ❌ Não Descrição opcional do saque
🎯
Detecção Automática: Se você não informar o pixKeyType, nossa API detecta automaticamente baseado no formato da chave (CPF, CNPJ, Email, Telefone, UUID).

Tipos de Chave PIX

Tipo Formato Exemplo
EMAIL Email válido usuario@email.com
CPF 11 dígitos 12345678901
CNPJ 14 dígitos 12345678000123
PHONE Telefone brasileiro +5521999999999
RANDOM Chave aleatória (UUID) 123e4567-e89b-12d3-a456...

Exemplos de Código

cURL - Exemplo Simples
curl -X POST "https://api.blackcatpagamentos.online/api/sales/create-withdrawal" \
  -H "X-API-Key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "pixKey": "usuario@email.com"
  }'
cURL - Telefone
curl -X POST "https://api.blackcatpagamentos.online/api/sales/create-withdrawal" \
  -H "X-API-Key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "pixKey": "+5521999999999",
    "description": "Saque via API"
  }'
TypeScript
interface WithdrawalRequest {
  amount: number;     // Valor em reais
  pixKey: string;     // Chave PIX
  method?: string;    // Opcional (padrão: PIX)
  pixKeyType?: string; // Opcional (detectado automaticamente)
  description?: string; // Opcional
}

interface WithdrawalResponse {
  success: boolean;
  data: {
    id: string;
    amount: number;
    amountFormatted: string;
    status: 'PROCESSING' | 'PENDING' | 'COMPLETED' | 'CANCELLED';
    // ... outros campos
  };
}

const createWithdrawal = async (request: WithdrawalRequest): Promise => {
  const response = await fetch('https://api.blackcatpagamentos.online/api/sales/create-withdrawal', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'sua_api_key_aqui'
    },
    body: JSON.stringify(request)
  });
  
  return response.json();
};

// Uso
const result = await createWithdrawal({
  amount: 100.50,
  pixKey: 'usuario@email.com',
  description: 'Saque automático'
});

console.log('Saque criado:', result.data.id);
JavaScript
const createWithdrawal = async (withdrawalData) => {
  try {
    const response = await fetch('https://api.blackcatpagamentos.online/api/sales/create-withdrawal', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'sua_api_key_aqui'
      },
      body: JSON.stringify(withdrawalData)
    });
    
    const result = await response.json();
    
    if (result.success) {
      console.log('✅ Saque criado com sucesso!');
      console.log('ID:', result.data.id);
      console.log('Status:', result.data.status);
      console.log('Valor líquido:', result.data.netAmountFormatted);
    } else {
      console.error('❌ Erro ao criar saque:', result.message);
    }
    
    return result;
    
  } catch (error) {
    console.error('Erro na requisição:', error);
    throw error;
  }
};

// Exemplo de uso
createWithdrawal({
  amount: 75.00,
  pixKey: '+5521987654321',
  description: 'Saque de emergência'
});
PHP
 $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($withdrawalData),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $apiKey
        ],
    ]);
    
    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode !== 200) {
        throw new Exception("Erro HTTP: $httpCode");
    }
    
    return json_decode($response, true);
}

try {
    $apiKey = 'sua_api_key_aqui';
    
    $withdrawalData = [
        'amount' => 100.50,
        'pixKey' => 'empresa@exemplo.com',
        'description' => 'Saque mensal'
    ];
    
    $result = createWithdrawal($apiKey, $withdrawalData);
    
    if ($result['success']) {
        echo "✅ Saque criado com sucesso!\n";
        echo "ID: " . $result['data']['id'] . "\n";
        echo "Status: " . $result['data']['status'] . "\n";
        echo "Valor líquido: " . $result['data']['netAmountFormatted'] . "\n";
    } else {
        echo "❌ Erro: " . $result['message'] . "\n";
    }
    
} catch (Exception $e) {
    echo "Erro na requisição: " . $e->getMessage() . "\n";
}

?>

Exemplo de Resposta de Sucesso

Resposta JSON
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.50,
    "amountFormatted": "R$ 100,50",
    "fees": 2.50,
    "feesFormatted": "R$ 2,50",
    "netAmount": 98.00,
    "netAmountFormatted": "R$ 98,00",
    "method": "PIX",
    "pixKeyType": "EMAIL",
    "pixKey": "usuario@email.com",
    "status": "PROCESSING",
    "autoWithdrawal": true,
    "createdAt": "2026-01-27T20:00:00.000Z",
    "message": "Saque criado e enviado automaticamente para processamento."
  }
}

Possíveis Erros

Valor mínimo não atingido
{
  "success": false,
  "message": "Valor mínimo para saque é R$ 2,00"
}
Saldo insuficiente
{
  "success": false,
  "message": "Saldo insuficiente. Disponível para saque: R$ 45,30",
  "data": {
    "available": 45.30,
    "requested": 100.00
  }
}
API não habilitada
{
  "success": false,
  "message": "Saques via API não estão habilitados para esta empresa. Entre em contato com o suporte."
}
⚠️
Importante:
  • Valores são informados em reais (formato decimal)
  • Taxas são automaticamente calculadas e deduzidas
  • Processamento pode ser automático ou manual
  • Existe valor mínimo configurável por empresa

Webhooks

Webhooks permitem que você receba notificações em tempo real sobre eventos que acontecem na sua conta, como pagamentos confirmados e saques processados.

Como Funcionam

Quando um evento ocorre (ex: pagamento PIX confirmado), enviamos uma requisição POST para a URL que você configurou com os dados do evento.

Headers Enviados

Header Descrição
Content-Type application/json
X-Webhook-Event Nome do evento (ex: transaction.paid)
X-Webhook-Source blackcat-api

Boas Práticas

💡
  • Responda com status 200 em até 10 segundos
  • Processe os webhooks de forma assíncrona
  • Implemente idempotência usando o transactionId
  • Verifique se o status mudou antes de processar

Dados UTM nos Webhooks

Se dados UTM foram fornecidos na criação da transação, eles são automaticamente incluídos nos webhooks para que você possa rastrear a origem das suas vendas.

🏷️
Campos UTM Disponíveis:
  • utm_source: Origem do tráfego (google, facebook, newsletter)
  • utm_medium: Meio utilizado (cpc, email, organic)
  • utm_campaign: Nome da campanha (promo_janeiro, black_friday)
  • utm_content: Conteúdo específico (banner_top, link_footer)
  • utm_term: Termo de pesquisa (pagamento_pix, checkout)

Eventos de Webhook

Lista de todos os eventos disponíveis e exemplos de payload.

transaction.created Transação

Disparado quando uma nova transação é criada.

Payload
{
  "event": "transaction.created",
  "timestamp": "2025-12-08T10:30:00.000Z",
  "transactionId": "TXN-1733654321-ABC123",
  "externalReference": "ORDER-12345",
  "status": "PENDING",
  "amount": 9990,
  "netAmount": 9691,
  "fees": 299,
  "paymentMethod": "PIX",
  "acquirer": "payzu",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com"
  },
  "utm": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "promo_janeiro",
    "utm_content": "banner_top",
    "utm_term": "pagamento_pix"
  }
}
transaction.paid Transação

Disparado quando um pagamento é confirmado.

Payload
{
  "event": "transaction.paid",
  "timestamp": "2025-12-08T10:35:00.000Z",
  "transactionId": "TXN-1733654321-ABC123",
  "externalReference": "ORDER-12345",
  "status": "PAID",
  "amount": 9990,
  "netAmount": 9691,
  "fees": 299,
  "paymentMethod": "PIX",
  "acquirer": "payzu",
  "acquirerTransactionId": "pix_abc123def456",
  "paidAt": "2025-12-08T10:35:00.000Z",
  "endToEndId": "E12345678202312081035XYZ123",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com"
  },
  "utm": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "promo_janeiro",
    "utm_content": "banner_top",
    "utm_term": "pagamento_pix"
  }
}
transaction.failed Transação

Disparado quando uma transação falha ou expira.

Payload
{
  "event": "transaction.failed",
  "timestamp": "2025-12-08T11:30:00.000Z",
  "transactionId": "TXN-1733654321-ABC123",
  "externalReference": "ORDER-12345",
  "status": "CANCELLED",
  "amount": 9990,
  "paymentMethod": "PIX",
  "reason": "PIX expirado"
}
withdrawal.created Saque

Disparado quando um novo saque é solicitado.

Payload
{
  "event": "withdrawal.created",
  "timestamp": "2025-12-08T14:00:00.000Z",
  "withdrawalId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "amount": 50000,
  "fees": 150,
  "netAmount": 49850,
  "method": "PIX",
  "pixKeyType": "EMAIL",
  "pixKey": "empresa@email.com",
  "createdAt": "2025-12-08T14:00:00.000Z"
}
withdrawal.completed Saque

Disparado quando um saque é processado com sucesso.

Payload
{
  "event": "withdrawal.completed",
  "timestamp": "2025-12-08T14:05:00.000Z",
  "withdrawalId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "amount": 50000,
  "fees": 150,
  "netAmount": 49850,
  "method": "PIX",
  "pixKeyType": "EMAIL",
  "pixKey": "empresa@email.com",
  "createdAt": "2025-12-08T14:00:00.000Z",
  "processedAt": "2025-12-08T14:05:00.000Z"
}
withdrawal.failed Saque

Disparado quando um saque falha.

Payload
{
  "event": "withdrawal.failed",
  "timestamp": "2025-12-08T14:05:00.000Z",
  "withdrawalId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "FAILED",
  "amount": 50000,
  "fees": 150,
  "netAmount": 49850,
  "method": "PIX",
  "pixKeyType": "EMAIL",
  "pixKey": "empresa@email.com",
  "createdAt": "2025-12-08T14:00:00.000Z",
  "processedAt": "2025-12-08T14:05:00.000Z"
}

Evento Especial: all

Ao cadastrar um webhook com o evento all, você receberá todos os eventos listados acima.

Códigos de Erro

Lista de códigos de status HTTP e mensagens de erro comuns.

Código Descrição Ação Sugerida
400 Bad Request - Dados inválidos Verifique o body da requisição
401 Unauthorized - API Key inválida Verifique sua API Key
403 Forbidden - Sem permissão Conta não aprovada ou bloqueada
404 Not Found - Recurso não encontrado Verifique o ID informado
422 Unprocessable Entity - Validação falhou Verifique os campos obrigatórios
429 Too Many Requests - Rate limit Aguarde antes de tentar novamente
500 Internal Server Error Erro interno, tente novamente

Estrutura de Erro

Resposta de Erro Padrão
{
  "success": false,
  "message": "Descrição do erro",
  "error": "Detalhes técnicos (opcional)"
}