API PIX Bspaybr

Introdução

Bem-vindo à documentação da API PIX da Bspaybr! Nosso objetivo é fornecer uma plataforma robusta e de fácil integração para todas as suas necessidades de pagamentos e transferências via PIX. Com nossa API, você pode:

• Gerar QR Codes PIX dinâmicos para recebimento.
• Realizar transferências PIX para qualquer chave.
• Consultar o status de transações em tempo real.
• Receber notificações de eventos via Webhooks.

Esta documentação guiará você passo a passo através de todos os endpoints, parâmetros e exemplos de código, garantindo uma integração suave e eficaz.

Autenticação

Todas as requisições para a API Bspaybr exigem autenticação para garantir a segurança dos seus dados. A autenticação é feita através do envio do seu `client_id` e `client_secret` em cada requisição POST, seja como parte do corpo da requisição (`Content-Type: application/x-www-form-urlencoded`) ou via cabeçalhos de autorização (para métodos GET, onde aplicável).

Obtendo suas Credenciais

Suas credenciais (`client_id` e `client_secret`) são fornecidas pela Bspaybr no momento do seu cadastro em nossa plataforma. Caso não as possua ou precise redefinir, entre em contato com nossa equipe de suporte.

client_id: "seu_client_id_unico"
client_secret: "seu_client_secret_altamente_secreto"

Gerar QR Code PIX

Este endpoint permite a criação de um QR Code PIX para que seus clientes possam realizar pagamentos de forma rápida e segura. É ideal para e-commerce, faturas e sistemas de cobrança.

Endpoint

POST https://bspaybr.com/v3/pix/qrcode

Parâmetros da Requisição

Exemplo de Código (PHP)

<?php
$apiUrl = 'https://bspaybr.com/v3/pix/qrcode';

$postData = [
    'client_id' => 'seu_client_id_aqui',
    'client_secret' => 'seu_client_secret_aqui',
    'nome' => 'João Silva',
    'cpf' => '12345678901',
    'valor' => 150.99,
    'descricao' => 'Pagamento da Fatura #12345',
    'urlnoty' => 'https://seuservidor.com/webhook/pix-qrcode'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);

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

$data = json_decode($response, true);

if ($httpCode === 200 && isset($data['qrcode'])) {
    echo "QR Code gerado com sucesso! QRCode: " . $data['qrcode'] . "\n";
    echo "Transaction ID: " . $data['transactionId'] . "\n";
} else {
    echo "Erro ao gerar QR Code (" . $httpCode . "): " . (isset($data['message']) ? $data['message'] : 'Erro desconhecido') . "\n";
}
?>

Resposta de Sucesso (Status 200)

{
    "transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
    "status": "PENDING",
    "amount": 150.99,
    "qrcode": "00020126850014br.gov.bcb.pix2563pix.bspaybr.com/qr/v3/at/6ed39bf2...",
    "reference_code": "algum_codigo_de_referencia_gerado_pela_bspaybr"
}

A chave `qrcode` contém o payload do QR Code. Você pode renderizá-lo usando uma biblioteca de QR Code ou exibi-lo diretamente se for uma imagem base64.

Transferência PIX

Este endpoint permite a realização de transferências PIX diretas da sua conta Bspaybr para qualquer chave PIX. Ideal para pagamentos a fornecedores, reembolsos ou saques automatizados.

Endpoint

POST https://bspaybr.com/v3/pix/payment

Parâmetros da Requisição

Exemplo de Código (PHP)

<?php
$apiUrl = 'https://bspaybr.com/v3/pix/payment';

$postData = [
    'client_id' => 'seu_client_id_aqui',
    'client_secret' => 'seu_client_secret_aqui',
    'nome' => 'Sua Empresa LTDA',
    'cpf' => '00000000000000', // CPF/CNPJ da sua empresa
    'valor' => 250.75,
    'chave_pix' => '[email protected]', // Chave PIX do destinatário
    'urlnoty' => 'https://seuservidor.com/webhook/pix-transferencia'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);

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

$data = json_decode($response, true);

if ($httpCode === 200 && isset($data['statusCode']) && $data['statusCode'] == 200) {
    echo "Transferência PIX iniciada com sucesso! Mensagem: " . $data['message'] . "\n";
} else {
    echo "Erro ao iniciar transferência (" . $httpCode . "): " . (isset($data['message']) ? $data['message'] : 'Erro desconhecido') . "\n";
}
?>

Resposta de Sucesso (Status 200)

[{
    "statusCode": 200,
    "message": "Transferência PIX processada com sucesso"
}]

Consultar Status de Transações

Acompanhe o status de qualquer transação (pagamento ou transferência) realizada através da Bspaybr utilizando o `reference_code` fornecido.

Endpoints

Você pode consultar o status utilizando tanto o método GET quanto POST:

Método GET

GET https://bspaybr.com/libs/consult/transaction_status?id={reference_code}

Método POST

POST https://bspaybr.com/libs/consult/transaction_status
Content-Type: application/json

{
    "id": "{reference_code}"
}

Parâmetros da Requisição

Exemplo de Código (PHP)

<?php
// Exemplo com Método GET
$referenceCodeGet = "seu_codigo_de_referencia_get";
$urlGet = "https://bspaybr.com/libs/consult/transaction_status?id=" . urlencode($referenceCodeGet);

$chGet = curl_init($urlGet);
curl_setopt($chGet, CURLOPT_RETURNTRANSFER, true);
$responseGet = curl_exec($chGet);
$httpCodeGet = curl_getinfo($chGet, CURLINFO_HTTP_CODE);
curl_close($chGet);

echo "--- Consulta GET ---\n";
echo "HTTP Status: " . $httpCodeGet . "\n";
echo "Resposta: " . $responseGet . "\n\n";

// Exemplo com Método POST
$referenceCodePost = "seu_codigo_de_referencia_post";
$postDataConsult = [
    "id" => $referenceCodePost
];

$chPost = curl_init("https://bspaybr.com/libs/consult/transaction_status");
curl_setopt($chPost, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chPost, CURLOPT_POST, true);
curl_setopt($chPost, CURLOPT_POSTFIELDS, json_encode($postDataConsult));
curl_setopt($chPost, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$responsePost = curl_exec($chPost);
$httpCodePost = curl_getinfo($chPost, CURLINFO_HTTP_CODE);
curl_close($chPost);

echo "--- Consulta POST ---\n";
echo "HTTP Status: " . $httpCodePost . "\n";
echo "Resposta: " . $responsePost . "\n";
?>

Resposta de Sucesso (Status 200)

{
    "Bank": "Bspaybr",
    "data": {
        "external_id": "seu_codigo_de_referencia",
        "status": "PAID",
        "amount": "100.00",
        "confirmed_date": "2025-03-13 12:00:00",
        "postback_url": "https://seusite.com/webhook"
    }
}

Status da Transação:

• `PAID`: A transação foi paga e confirmada.
• `PENDING`: A transação está aguardando pagamento.
• `CANCELED`: A transação foi cancelada.

Webhooks: Notificações em Tempo Real

Os Webhooks da Bspaybr permitem que sua aplicação receba notificações automáticas sobre o status das transações, eliminando a necessidade de polling constante. Sempre que um evento significativo ocorrer (ex: pagamento confirmado, transferência concluída), enviaremos um `POST` para a `urlnoty` que você especificou na requisição original.

Recebendo Notificações da Bspaybr (Seu Webhook)

Para que você receba notificações de pagamentos, transferências e outros eventos diretamente do nosso sistema, configure o seu endpoint de webhook e nos forneça a URL dele quando gerar um QR Code ou iniciar uma transferência. Nossa plataforma enviará um `POST` para a URL que você nos informar (`urlnoty`).

O endpoint padrão para o qual a Bspaybr envia as notificações é:

POST https://bspaybr.com/libs/primepag/webhook.php

Para cada evento, nosso sistema enviará um payload JSON no corpo da requisição POST para esta URL.

Segurança e Validação da Requisição

A segurança é nossa prioridade. Para garantir a autenticidade e a integridade das notificações enviadas ao seu webhook, exigimos a validação de cabeçalhos específicos:

• `X-SIGNATURE` (Obrigatório): Este é o hash HMAC-SHA256 do corpo completo da requisição (o payload JSON), gerado pela Bspaybr usando uma chave secreta compartilhada.

• `X-SECURE-TOKEN` (Opcional/Para compatibilidade): Este cabeçalho pode ser enviado pela Bspaybr e, se presente, seu sistema pode usá-lo para verificações adicionais ou para compatibilidade, embora a validação principal seja via `X-SIGNATURE`.

Para validar a `X-SIGNATURE`, você precisará da Chave Secreta de Webhook da Bspaybr. Esta é uma chave única que a Bspaybr utiliza para assinar todas as notificações de webhook que envia. Ao receber um webhook, seu sistema deve usar esta mesma chave para calcular a assinatura e comparar com a `X-SIGNATURE` recebida.

Como obter sua Chave Secreta de Webhook:

Sua Chave Secreta de Webhook é fornecida aos nossos parceiros através do nosso suporte 24 horas. Por favor, entre em contato para obtê-la. É fundamental que você armazene essa chave de forma extremamente segura e nunca a exponha publicamente ou em seu código-fonte.

Exemplo Simplificado de Conexão e Validação (PHP)

Este exemplo ilustra como seu sistema deve receber e validar uma notificação da Bspaybr.

<?php

// 1. Obtenha sua Chave Secreta de Webhook da Bspaybr.
//    Armazene-a de forma segura (ex: variável de ambiente, arquivo de configuração).
$webhookSecret = 'A_CHAVE_SECRETA_DA_BSPAYBR_QUE_VOCE_RECEBEU'; 

// 2. Obtenha o corpo RAW (bruto) da requisição POST.
//    Isso é crucial para a validação da assinatura.
$payload = file_get_contents('php://input');

// 3. Obtenha a assinatura enviada pela Bspaybr no cabeçalho X-SIGNATURE.
$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// 4. Calcule a assinatura esperada no seu lado.
//    O algoritmo (sha256) e a chave secreta devem ser os mesmos que a Bspaybr usou.
$computedSignature = hash_hmac('sha256', $payload, $webhookSecret);

// 5. Compare as assinaturas de forma segura.
if (hash_equals($computedSignature, $receivedSignature)) {
    // A ASSINATURA É VÁLIDA: O webhook é autêntico e íntegro!
    // Você pode agora decodificar e processar o payload JSON.
    $data = json_decode($payload, true);

    // ... sua lógica de processamento aqui ...
    error_log("Webhook válido recebido. Transação ID: " . ($data['requestBody']['transactionId'] ?? 'N/A'));

    // SEMPRE responda com HTTP 200 OK para a Bspaybr.
    http_response_code(200);
    echo "OK";

} else {
    // ASSINATURA INVÁLIDA: O webhook é falso ou foi adulterado. Descarte-o!
    error_log("Webhook inválido: Assinatura não confere. IP: " . ($_SERVER['REMOTE_ADDR'] ?? 'unknown') . " em " . date('Y-m-d H:i:s') . " | Assinatura Recebida: " . $receivedSignature . " | Assinatura Calculada: " . $computedSignature);
    http_response_code(403); // Acesso proibido
    die("Acesso não autorizado: Assinatura inválida.");
}

?>

Testar Webhook (Consulta de Evento)

Use esta ferramenta para consultar o status de uma transação específica e ver o payload que seria enviado ao seu webhook. Isso ajuda a verificar se a integração está funcionando corretamente.

Nota: Para que esta ferramenta funcione, você precisará configurar um endpoint no seu servidor (ex: `/api/webhook-test-query`) que receba o `transactionId` e o `testApiToken`, consulte o banco de dados e retorne os dados no formato do webhook. O `testApiToken` deve ser um token de API que você gerencia e que permite apenas a consulta de dados para o usuário autenticado, e NÃO o seu `WEBHOOK_SECRET_TOKEN` principal.

Formatos de Payload dos Webhooks

Abaixo estão os formatos de payload JSON que você pode esperar receber em seu webhook, dependendo do tipo de evento:

Evento: Pagamento Recebido (PIX)

Este webhook é acionado quando um pagamento PIX destinado a você é recebido e confirmado em nossa plataforma. Contém detalhes do pagador e da transação.

{
    "requestBody": {
        "transactionType": "RECEIVEPIX",
        "transactionId": "c327ce8bee2a18565ec2m1zdu6px2keu",
        "external_id": "55aefd02e54e785fbb5a80faa19f8802",
        "amount": 15.00,
        "paymentType": "PIX",
        "status": "PAID",
        "dateApproval": "2024-10-07 16:07:10",
        "creditParty": {
            "name": "Henrique Silva",
            "email": "[email protected]",
            "taxId": "99999999999"
        },
        "debitParty": {
            "bank": "Bspaybr SOLUCOES DE PAGAMENTOS LTDA",
            "taxId": "46872831000154"
        }
    }
}

Evento: Transferência Concluída (PIX)

Este webhook é enviado quando uma transferência PIX que você iniciou via API é processada e concluída com sucesso.

{
    "transactionType": "PAYMENT",
    "transactionId": "798176179",
    "external_id": "ebceb2b835598ccad73ce42eb5etrh2m5",
    "amount": 1.00,
    "dateApproval": "2024-12-19 17:10:54",
    "statusCode": {
        "statusId": 1,
        "description": "Pagamento aprovado"
    }
}

Evento: QR Code Pago

Notificação específica para quando um QR Code gerado por você através do endpoint `/pix/qrcode` é pago pelo cliente.

{
    "value_cents": 15000,
    "reference_code": "QRCODE123",
    "external_reference": "pedido-789",
    "content": { "item": "produto A" },
    "status": "paid",
    "generator_name": "Loja Exemplo",
    "generator_document": "12.345.678/0001-90",
    "payer_name": "Cliente Silva",
    "payer_document": "123.456.789-00",
    "registration_date": "2025-05-08T14:00:00",
    "payment_date": "2025-05-08T14:05:00",
    "end_to_end": "XYZ987654321"
}

Evento: Pagamento PIX Genérico

Um webhook mais genérico para eventos de pagamento PIX, que pode ser enviado para diversas origens de pagamentos.

{
    "value_cents": 5000,
    "reference_code": "PIXPAY456",
    "external_reference": "pedido-321",
    "content": null,
    "status": "completed",
    "generator_name": "Cliente Silva",
    "generator_document": "123.456.789-00",
    "payer_name": "Loja Exemplo",
    "payer_document": "12.345.678/0001-90",
    "registration_date": "2025-05-08T15:00:00",
    "payment_date": "2025-05-08T15:02:00",
    "end_to_end": "ABC123XYZ789"
}

Códigos de Erro e Respostas Comuns

Compreender os códigos de resposta da API é fundamental para depurar e tratar erros na sua integração. Abaixo, listamos os códigos de status HTTP e os formatos de resposta mais comuns para situações de erro.

Status HTTP e Mensagens de Erro

{ "statusCode": 400, "message": "Parâmetros 'valor' é obrigatório e deve ser numérico." }

{ "statusCode": 401, "message": "Credenciais de API inválidas." }

{ "statusCode": 403, "message": "Saldo insuficiente para completar a operação." }

{ "statusCode": 404, "message": "Transação não encontrada para o ID fornecido." }

{ "statusCode": 429, "message": "Você excedeu o limite de requisições. Tente novamente mais tarde." }

{ "statusCode": 500, "message": "Um erro interno ocorreu. Por favor, tente novamente ou contate o suporte." }