Integração Oficial

BXCodex Gateway API

Bem-vindo à documentação oficial da BXCodex Gateway. Esta API foi desenvolvida para você integrar pagamentos PIX instantâneos na sua plataforma de rastreio, loja virtual, infoprodutos ou sistema SaaS, com confirmação automática em tempo real via Webhook.

Geração Instantânea

Crie cobranças com QR Code dinâmico e código Copia e Cola em milissegundos.

Confirmação por Webhook

Seu sistema recebe notificações automáticas no momento exato em que o cliente paga.

Retentativas Automáticas

Se a sua plataforma estiver momentaneamente offline, o evento é reenviado com segurança.

Como integrar em 3 passos:

1

Obtenha sua API Key no Painel

Acesse seu painel BXCodex em Integrações e copie sua Chave Secreta (bx_sec_...).

2

Gere o PIX na sua Plataforma

Ao finalizar um pedido, faça uma chamada POST /v1/payments para receber o QR Code dinâmico.

3

Receba a Confirmação via Webhook

Suba o arquivo webhook.php no seu servidor para liberar o pedido/rastreio automaticamente assim que o PIX for pago.

Autenticação

Credenciais & Headers

Todas as requisições enviadas pela sua plataforma para a API da BXCodex devem ser autenticadas através do cabeçalho HTTP Authorization contendo sua Chave Secreta gerada no painel.

Header de Autorização Obrigatório

Authorization: Bearer bx_sec_sua_chave_secreta_aqui
Content-Type: application/json

URL Base da API

Utilize o endpoint oficial de produção:

https://api.bxcodex.com/v1

Valores Monetários

Todos os valores na API BXCodex são informados em centavos de Real (BRL). Exemplo: 15000 equivale a R$ 150,00.

Cobranças

Criar Pagamento PIX

Utilize este endpoint na sua plataforma de rastreio ou loja para gerar o PIX do cliente.

POST /v1/payments

Parâmetros no Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor em centavos (ex: 15000 = R$ 150,00)
`external_reference`	string	Recomendado	ID do pedido no seu sistema (ex: COD-RASTREIO-1092)
`customer.name`	string	Sim	Nome completo do cliente
`customer.document`	string	Sim	CPF ou CNPJ válido do pagador
`customer.email`	string	Opcional	E-mail do cliente
`customer.phone`	string	Opcional	Telefone com DDD (ex: 31982661187)

Exemplo de Requisição (JSON)

{
  "amount": 15000,
  "description": "Taxa de Rastreio Express",
  "external_reference": "COD-RASTREIO-1092",
  "customer": {
    "name": "Cliente Teste Rastreio",
    "email": "cliente@exemplo.com",
    "phone": "31982661187",
    "document": "12345678909"
  }
}

Resposta da API (201 Created)

{
  "id": "pay_bx_987654321",
  "status": "pending",
  "amount": 15000,
  "pix": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_url": "https://api.bxcodex.com/v1/pix/qrcode/pay_bx_987654321.png",
    "expires_at": "2026-10-02T12:30:00Z"
  }
}

Notificações

Script Oficial webhook.php

Este arquivo foi criado para você colocar na sua plataforma ou servidor de aplicação. Ele escuta as notificações enviadas pela BXCodex e atualiza o seu banco de dados automaticamente.

Baixar webhook.php Pronto

Como liberar o pedido no seu webhook.php

switch ($eventType) {
    case 'payment.approved':
    case 'payment.paid':
        $paymentId      = $eventData['id'];
        $amountCents    = $eventData['amount'];               // 15000 = R$ 150,00
        $externalRef    = $eventData['external_reference'];   // ID do seu Pedido de Rastreio
        $customerName   = $eventData['customer']['name'];
        $customerEmail  = $eventData['customer']['email'];

        // 1. Atualizar seu banco de dados (ex: MySQL/PostgreSQL):
        $stmt = $pdo->prepare("UPDATE pedidos SET status = 'PAGO', pago_em = NOW() WHERE codigo_pedido = ?");
        $stmt->execute([$externalRef]);

        // 2. Liberar o código de rastreamento ou disparar WhatsApp:
        enviarMensagemWhatsApp($customerPhone, "Seu pagamento foi confirmado! Rastreio liberado.");
        break;
}

Auditoria de Pagamentos

O script cria automaticamente um arquivo bxcodex_webhooks.log na mesma pasta onde for instalado. Assim você sempre pode verificar o histórico de notificações recebidas em tempo real.

Payloads

Eventos Enviados pelo Webhook

Sempre que uma cobrança PIX mudar de status, a BXCodex fará um POST com corpo JSON para a URL que você cadastrou no seu painel.

POST payment.approved (PIX Pago/Aprovado)

{
  "id": "evt_pix_123456789",
  "event": "payment.approved",
  "created_at": "2026-10-02T12:00:00Z",
  "data": {
    "id": "pay_bx_987654321",
    "status": "approved",
    "amount": 15000,
    "currency": "BRL",
    "external_reference": "COD-RASTREIO-1092",
    "paid_at": "2026-10-02T12:00:00Z",
    "customer": {
      "id": "cus_bx_111",
      "name": "Cliente Teste Rastreio",
      "email": "cliente@gmail.com",
      "phone": "31982661187",
      "document": "12345678909"
    }
  }
}

POST withdrawal.completed (Saque Concluído)

{
  "id": "evt_with_99999",
  "event": "withdrawal.completed",
  "created_at": "2026-10-02T12:10:00Z",
  "data": {
    "id": "with_bx_555",
    "status": "completed",
    "amount": 50000,
    "pix_key": "bxcodexsuporte@gmail.com",
    "pix_key_type": "EMAIL"
  }
}

Financeiro

Consultar Saldo da Conta

Consulte o saldo disponível e valores pendentes em liquidação da sua conta BXCodex.

GET /v1/balance

{
  "available_amount": 450000,
  "pending_amount": 15000,
  "currency": "BRL"
}

Criptografia

Validação de Assinatura (HMAC SHA-256)

Para garantir que as notificações recebidas vieram 100% da BXCodex, você pode validar a assinatura enviada no header X-BXCodex-Signature.

Validação no webhook.php

$rawBody = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_BXCODEX_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac('sha256', $rawBody, BXCODEX_WEBHOOK_SECRET);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Assinatura inválida']));
}