Documentação da API BTPay

Bem-vindo à documentação da API BTPay! Aqui você encontrará todas as informações necessárias para integrar nossa solução de pagamentos ao seu projeto de forma simples e eficiente.

Autenticação

Para acessar a API BTPay, você precisa de um access token. Após registrar-se, sua chave estará disponível na sua conta em Gerenciar Conta.

Todas as requisições devem incluir o header Authorization com o valor Bearer {access-token}.

Exemplo de Requisição

curl -X POST "https://btpay.com.br/api/pix-cob" \
-H "Authorization: Bearer seu-access-token" \
-H "Content-Type: application/json"
                

Caso a autenticação falhe, você receberá um erro 401 Unauthorized.

Criando um Pagamento PIX

Para criar um pagamento PIX, envie uma requisição POST para o endpoint /api/pix-cob.

Exemplo de Requisição

    $btaccess_token = '9d1d5bab-ac86-4200-90b8-3dc8d5ab5d5e';
    $btaccount = '654643-1';
    $bturl = 'https://btpay.com.br/api/pix-cob';

    $minutosExpiracao = '5';
    
    // Dados da requisição para criar o Pix QR Code
    $data = [
        'expiresIn' => $minutosExpiracao * 60,
        'amount' => [
            'original' => 150.00,
            'allowCustomerChangeValue' => false
        ],
        "tags" => [
            "accountlId" => $btaccount,
            "external_reference" => "Identificador-fornecido",
        ],
        'displayText' => "Compra de produto"
    ];
    
    // Converte os dados para JSON
    $json_data = json_encode($data);
    
    // Inicializa o cURL
    $ch = curl_init($bturl);
    
    // Configurações do cURL
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Accept: application/json',
        'Authorization: Bearer ' . $btaccess_token,
        'Content-Type: application/json',
        'Content-Length: ' . strlen($json_data)
    ]);
    
    // Executa a requisição e armazena o resultado
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    
    // Fecha a conexão
    curl_close($ch);
    
    // Verifica se houve erro no cURL
    if ($curlResponse === false) {
        throw new Exception("Erro na requisição cURL: " . $error);
    }

    // Decodifica a resposta JSON
    $responsePIX = json_decode($curlResponse, true);

    // Verifica se a resposta é válida
    if ($http_code !== 201 || !$responsePIX || !is_array($responsePIX)) {
        throw new Exception("Erro na API BTPay: HTTP $http_code - " . ($responsePIX['error'] ?? $curlResponse));
    }

    // Extrai os dados da resposta
    $txId = $responsePIX['txid'] ?? null;
    $qrCodeUrl = $responsePIX['pixCopiaECola'] ?? null;
    
    // Constrói o array de resposta
    $response = [
        'txId' => $txId,
        'qrCodeUrl' => $qrCodeUrl
    ];

    // Exibe ou retorna a resposta (ajuste conforme o contexto)
    echo json_encode($response, JSON_PRETTY_PRINT);
                

Resposta

[
    {
        "loc": {
            "id": 109868065,
            "location": "https://btpay.com.br/spi/pj/v2/4ab2fe8f40724202ae8f2bbb234e0243",
            "tipoCob": "cob",
            "criacao": "2025-03-28T12:40:06.24Z"
        },
        "location": "https://btpay.com.br/spi/pj/v2/4ab2fe8f40724202ae8f2bbb234e0243",
        "status": "ATIVA",
        "valor": {
            "original": "150.00",
            "modalidadeAlteracao": 1
        },
        "calendario": {
            "expiracao": 300,
            "criacao": "2025-03-28T12:40:06.256Z"
        },
        "txid": "7czn4dupq82w5gs7it7he8j18xkerg9kcwf",
        "revisao": 0,
        "pixCopiaECola": "00020101021226930014BR.GOV.BCB.PIX2571spi-qrcode.btpay.com.br/spi/pj/v2/4ab2fe8f40724202ae8f2bbb234e024352040000530398654041.005802BR5901*6013FLORIANOPOLIS61088806041062070503***630440A6",
        "solicitacaoPagador": "Compra de produto"
    }
]
                

Configurando Webhook

Configure um webhook para receber notificações sobre o status dos pagamentos. O endpoint deve ser configurado em Gerenciar Conta e aceitar requisições POST.

Exemplo de Payload

{
    "pix": [
        {
            "txid": "j82pc84xpio15cmu20f5bxhmjdzp7rlbomp",
            "valor": "150.00",
            "horario": "2025-03-28T02:51:26.996Z",
            "componentesValor": {
                "original": {
                    "valor": "150.00"
                }
            },
            "pagador": {
                "nome": "NOME DO PAGADOR",
                "cpfCnpj": "***078771**"
            },
            "tags": {
                "external_reference": "955"
            }
        }
    ]
}
                

Exemplo em Laravel

Adicione a seguinte rota no seu arquivo routes/api.php:

Route::post('/webhook-btpay', [WebhookController::class, 'handle']);
                

E no controlador WebhookController.php:

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Obtém os dados do corpo da requisição (JSON)
        $data = $request->json()->all();

        // Verifica se os dados estão vazios ou não têm a estrutura esperada
        if (empty($data) || !isset($data['pix']) || empty($data['pix'])) {
            return response()->json(['error' => 'Dados inválidos ou ausentes.'], 400);
        }
    
        // Pega a primeira transação Pix do array
        $pix = $data['pix'][0];
        
        // Extrai os dados do payload
        $txId = $pix['txid'];         // "udy70l4ljpb8zh8xvogtbkxr1e4vorj4h95"
        $externalId = $pix['external_reference'];         // "Identificador-fornecido"
        $paidAmount = floatval($pix['valor']);  // Converte "1.00" para 1.00 (float)
        
        \Log::info('Dados recebidos com sucesso do webhook', [
            'externalId' => externalId,
            'txId' => $txId,
            'Value' => $paidAmount,
        ]);
                
        return response()->json(['status' => 'processed'], 200);
    }
}
                

Erros Comuns

• 401 Unauthorized: Chave de API inválida ou ausente.
• 400 Bad Request: Parâmetros inválidos ou ausentes na requisição.
• 500 Internal Server Error: Erro no servidor, entre em contato com o suporte.

Próximos Passos

Pronto para começar? Registre-se agora e obtenha sua chave de API no painel de controle.