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://blackcatapi.squarify.co/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://blackcatapi.squarify.co/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. Suporta PIX, Cartão de Crédito e Boleto.

POST /sales/create-sale

Parâmetros do Body

Campo	Tipo	Descrição
`amount` *	integer	Valor em centavos. Ex: 9990 = R$ 99,90
`paymentMethod` *	string	`PIX`, `CREDIT_CARD`, `DEBIT_CARD`, `BOLETO`
`externalReference`	string	Seu identificador único para esta venda
`customer` *	object	Dados do cliente (veja abaixo)
`items` *	array	Lista de itens da venda
`pix`	object	Configurações específicas do PIX
`postbackUrl`	string	URL para receber notificações (webhook legado)

Objeto Customer

Campo	Tipo	Descrição
`name` *	string	Nome completo do cliente
`email` *	string	E-mail do cliente
`document` *	object	`{"type": "CPF", "number": "12345678900"}`
`phone`	string	Telefone (apenas números)

Exemplo de Requisição - PIX

Request Body

{
  "amount": 9990,
  "paymentMethod": "PIX",
  "externalReference": "ORDER-12345",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "document": {
      "type": "CPF",
      "number": "12345678900"
    },
    "phone": "11999999999"
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "unitPrice": 9990
    }
  ],
  "pix": {
    "expiresInDays": 1
  }
}

Respostas

Response - 201 Created

{
  "success": true,
  "data": {
    "transactionId": "TXN-1733654321-ABC123",
    "status": "PENDING",
    "paymentMethod": "PIX",
    "amount": 9990,
    "netAmount": 9691,
    "fees": 299,
    "createdAt": "2025-12-08T10:30:00.000Z",
    "paymentData": {
      "id": "pix_abc123def456",
      "qrCode": "00020126580014br.gov.bcb.pix...",
      "qrCodeUrl": "https://api.example.com/pix/qrcode/abc123.png",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
      "copyPaste": "00020126580014br.gov.bcb.pix...",
      "expiresAt": "2025-12-09T10:30:00.000Z"
    }
  }
}

Response - 400 Bad Request

{
  "success": false,
  "message": "Dados inválidos",
  "error": "O campo 'amount' é obrigatório e deve ser maior que zero"
}

Outros Erros Possíveis

Response - 401 Unauthorized

{
  "success": false,
  "message": "API Key inválida ou não fornecida"
}

Response - 500 Internal Server Error

{
  "success": false,
  "message": "Failed to create PIX transaction",
  "error": "All acquirers failed to process payment"
}

Consultar Status

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

GET /sales/{transactionId}/status

Parâmetros de URL

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

Exemplo

cURL

curl -X GET https://blackcatapi.squarify.co/api/sales/TXN-1733654321-ABC123/status \
  -H "X-API-Key: sua_api_key_aqui"

Resposta

Response - 200 OK

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

Status Possíveis

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

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

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"
  }
}

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"
  }
}

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)"
}

🧪 API Tester

Teste as requisições da API diretamente aqui. Configure o método, URL, headers e body para enviar requisições em tempo real.

Exemplos Rápidos

API Key * Body (JSON) - Apenas para POST/PUT

ℹ️

Dica: A API Key é obrigatória para todas as requisições. Você pode obter sua API Key no painel administrativo da sua conta.