PHP

SDK oficial para integração com a API do Beehive Hub. Aceite pagamentos de forma simples e rápida.

Requisitos

PHP 8.2 ou superior
Extensão curl
Extensão json
Composer

Instalação

composer require paybeehive/beehivehub-php-sdk

Autenticação

Inicialize o SDK com a sua SECRET_KEY:

use BeehiveHub\SDK\BeehiveHubClient;

$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);

Ambiente Sandbox

Se quiser usar o ambiente de testes:

use BeehiveHub\SDK\BeehiveHubClient;

$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY'], [
    'environment' => 'sandbox',
]);

Primeiro uso

Exemplo de criação de uma transação Pix:

use BeehiveHub\SDK\BeehiveHubClient;

$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);

$response = $beehive->transactions->create([
    'amount' => 15990,
    'paymentMethod' => 'pix',
    'customer' => [
        'name' => 'Ana Souza',
        'email' => 'ana.souza@email.com',
        'document' => [
            'type' => 'cpf',
            'number' => '00000000191',
        ],
        'phone' => '11999999999',
    ],
    'items' => [
        [
            'title' => 'Pedido #1001',
            'unitPrice' => 15990,
            'quantity' => 1,
            'tangible' => true,
        ],
    ],
    'postbackUrl' => 'https://seusite.com/webhook',
    'metadata' => [
        'orderId' => '1001',
    ],
]);

Recursos disponíveis

O SDK possui métodos para os principais recursos da API:

transactions
customers
transfers
balance
recipients
bankAccounts
company
paymentLinks

Transações

Criar transação

$transaction = $beehive->transactions->create([
    'amount' => 8900,
    'paymentMethod' => 'pix',
    'customer' => [
        'name' => 'Carlos Lima',
        'email' => 'carlos@email.com',
        'document' => [
            'type' => 'cpf',
            'number' => '00000000191',
        ],
        'phone' => '11988888888',
    ],
    'items' => [
        [
            'title' => 'Produto teste',
            'unitPrice' => 8900,
            'quantity' => 1,
            'tangible' => true,
        ],
    ],
]);

Listar transações

$transactions = $beehive->transactions->list([
    'limit' => 50,
    'offset' => 0,
    'createdFrom' => '2026-01-01T00:00:00',
]);

Buscar transação por ID

$transaction = $beehive->transactions->get(123456);

Reembolsar transação

// Reembolso total
$fullRefund = $beehive->transactions->refund(123456);

// Reembolso parcial
$partialRefund = $beehive->transactions->refund(123456, 3000);

Atualizar status de entrega

$delivery = $beehive->transactions->updateDelivery(123456, [
    'status' => 'in_transit',
    'trackingCode' => 'BR123456789',
]);

Clientes

Criar cliente

$customer = $beehive->customers->create([
    'name' => 'Mariana Costa',
    'email' => 'mariana@email.com',
    'document' => [
        'type' => 'cpf',
        'number' => '98765432100',
    ],
    'phone' => '11977777777',
    'address' => [
        'street' => 'Rua Exemplo',
        'streetNumber' => '200',
        'complement' => 'Sala 3',
        'neighborhood' => 'Centro',
        'zipCode' => '01001000',
        'city' => 'São Paulo',
        'state' => 'SP',
        'country' => 'br',
    ],
]);

Listar clientes

O parâmetro email é obrigatório nessa listagem. A API não utiliza paginação convencional para este recurso.

$customers = $beehive->customers->list([
    'email' => 'cliente@example.com',
]);

Buscar cliente por ID

$customer = $beehive->customers->get(123456);

Transferências

Criar transferência

$transfer = $beehive->transfers->create([
    'amount' => 50000,
    'recipientId' => 916,
]);

Criar transferência com conta bancária

$transfer = $beehive->transfers->create([
    'amount' => 50000,
    'recipientId' => 916,
    'bankAccount' => [
        'bankCode' => '001',
        'agencyNumber' => '1234',
        'accountNumber' => '12345',
        'accountDigit' => '6',
        'type' => 'conta_corrente',
        'legalName' => 'Destinatário Teste',
        'documentNumber' => '12345678900',
        'documentType' => 'cpf',
    ],
]);

Buscar transferência por ID

$transfer = $beehive->transfers->get(123456);

Saldo

Consultar saldo

$balance = $beehive->balance->get();

echo 'Available: BRL ' . ($balance['amount'] / 100) . PHP_EOL;
echo 'Recipient ID: ' . $balance['recipientId'] . PHP_EOL;

Recebedores

Criar recebedor

$recipient = $beehive->recipients->create([
    'legalName' => 'Recebedor Teste Ltda',
    'document' => [
        'type' => 'cnpj',
        'number' => '58593776000142',
    ],
    'transferSettings' => [
        'transferEnabled' => true,
        'automaticAnticipationEnabled' => false,
        'anticipatableVolumePercentage' => 100,
    ],
    'bankAccount' => [
        'bankCode' => '001',
        'agencyNumber' => '1234',
        'accountNumber' => '12345',
        'accountDigit' => '6',
        'type' => 'conta_corrente',
        'legalName' => 'Recebedor Teste Ltda',
        'documentNumber' => '58593776000142',
        'documentType' => 'cnpj',
    ],
]);

Listar recebedores

$recipients = $beehive->recipients->list();

Buscar recebedor por ID

$recipient = $beehive->recipients->get(916);

Atualizar recebedor

$updated = $beehive->recipients->update(916, [
    'legalName' => 'Beehive Sandbox',
]);

Contas bancárias

Adicionar conta bancária a um recebedor

$bankAccount = $beehive->bankAccounts->create(916, [
    'bankCode' => '341',
    'agencyNumber' => '9876',
    'accountNumber' => '54321',
    'accountDigit' => '0',
    'type' => 'conta_poupanca',
    'legalName' => 'Empresa Teste Ltda',
    'documentNumber' => '60572883000136',
    'documentType' => 'cnpj',
]);

Listar contas bancárias

$accounts = $beehive->bankAccounts->list(916);

Empresa

Consultar dados da empresa

$company = $beehive->company->get();

Atualizar dados da empresa

$updated = $beehive->company->update([
    'invoiceDescriptor' => 'Beehive Hub',
    'details' => [
        'averageRevenue' => 10000,
        'averageTicket' => 100.5,
        'physicalProducts' => true,
        'productsDescription' => 'Produtos físicos',
        'siteUrl' => 'https://www.meusite.com.br',
        'phone' => '11999999999',
        'email' => 'contato@meusite.com.br',
    ],
]);

Links de pagamento

O SDK adiciona a propriedade url nas respostas de criação, consulta, listagem e atualização quando existe um alias.

Produção: https://link.conta.paybeehive.com.br/{alias}
Sandbox: https://link.sandbox.hopysplit.com.br/{alias}

Se alias não for enviado, o SDK gera automaticamente um código alfanumérico de 10 caracteres.

Criar link de pagamento

$paymentLink = $beehive->paymentLinks->create([
    'title' => 'novo link alterado',
    'alias' => 'alias_alterado',
    'amount' => 1000,
    'settings' => [
        'defaultPaymentMethod' => 'credit_card',
        'requestAddress' => true,
        'requestPhone' => true,
        'traceable' => true,
        'boleto' => [
            'enabled' => true,
            'expiresInDays' => 0,
        ],
        'pix' => [
            'enabled' => false,
            'expiresInDays' => 0,
        ],
        'card' => [
            'enabled' => false,
            'freeInstallments' => 1,
            'maxInstallments' => 12,
        ],
    ],
]);

// $paymentLink['url'] já vem montada

Listar links de pagamento

A API não aceita filtros por query parameters nesse recurso. A listagem retorna todos os links da empresa.

$paymentLinks = $beehive->paymentLinks->list();

Buscar link de pagamento por ID

$paymentLink = $beehive->paymentLinks->get(247);

Atualizar link de pagamento

A atualização aceita payload parcial, ou seja, você pode enviar apenas os campos que deseja alterar.

$updated = $beehive->paymentLinks->update(247, [
    'title' => 'novo link alterado',
    'alias' => 'alias_alterado',
    'amount' => 1000,
    'settings' => [
        'defaultPaymentMethod' => 'credit_card',
        'requestAddress' => true,
        'requestPhone' => true,
        'traceable' => true,
        'boleto' => [
            'enabled' => true,
            'expiresInDays' => 0,
        ],
        'pix' => [
            'enabled' => false,
            'expiresInDays' => 0,
        ],
        'card' => [
            'enabled' => false,
            'freeInstallments' => 1,
            'maxInstallments' => 12,
        ],
    ],
]);

Excluir link de pagamento

$beehive->paymentLinks->delete(247);

Tratamento de erros

O SDK expõe classes específicas para tratamento de erro:

BeehiveHubAPIError
BeehiveHubAuthenticationError
BeehiveHubValidationError
BeehiveHubNotFoundError
BeehiveHubRateLimitError
BeehiveHubNetworkError

Exemplo:

use BeehiveHub\SDK\BeehiveHubClient;
use BeehiveHub\SDK\Exceptions\BeehiveHubAPIError;
use BeehiveHub\SDK\Exceptions\BeehiveHubAuthenticationError;
use BeehiveHub\SDK\Exceptions\BeehiveHubValidationError;

$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);

try {
    $transaction = $beehive->transactions->create([
        'amount' => 10000,
        'paymentMethod' => 'pix',
        'customer' => [
            'name' => 'João Silva',
            'email' => 'joao@example.com',
            'document' => [
                'type' => 'cpf',
                'number' => '12345678900',
            ],
            'phone' => '11999999999',
        ],
    ]);

    echo 'Transaction created: ' . $transaction['id'];
} catch (BeehiveHubAuthenticationError $e) {
    echo 'Invalid API key: ' . $e->getMessage();
} catch (BeehiveHubValidationError $e) {
    echo 'Validation error: ' . $e->getMessage();
} catch (BeehiveHubAPIError $e) {
    echo 'API error: ' . $e->getMessage();
} catch (\Exception $e) {
    echo 'Unexpected error: ' . $e->getMessage();
}

Valores em centavos

Todos os valores monetários enviados para a API devem ser informados em centavos.

// R$ 100,00
'amount' => 10000

// R$ 1,50
'amount' => 150

// Convertendo reais para centavos
$reais = 100.0;
$centavos = (int) round($reais * 100);

Boas práticas de segurança

Nunca exponha sua SECRET_KEY
Valide os dados antes de enviar para a API
Use HTTPS
Implemente webhooks para acompanhar mudanças de status

# .env
BEEHIVE_SECRET_KEY=your_secret_key_here

// bootstrap.php
use BeehiveHub\SDK\BeehiveHubClient;

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);

Introdução

Integração

PHP

​Requisitos

​Instalação

​Autenticação

​Ambiente Sandbox

​Primeiro uso

​Recursos disponíveis

​Transações

​Criar transação

​Listar transações

​Buscar transação por ID

​Reembolsar transação

​Atualizar status de entrega

​Clientes

​Criar cliente

​Listar clientes

​Buscar cliente por ID

​Transferências

​Criar transferência

​Criar transferência com conta bancária

​Buscar transferência por ID

​Saldo

​Consultar saldo

​Recebedores

​Criar recebedor

​Listar recebedores

​Buscar recebedor por ID

​Atualizar recebedor

​Contas bancárias

​Adicionar conta bancária a um recebedor

​Listar contas bancárias

​Empresa

​Consultar dados da empresa

​Atualizar dados da empresa

​Links de pagamento

​Criar link de pagamento

​Listar links de pagamento

​Buscar link de pagamento por ID

​Atualizar link de pagamento

​Excluir link de pagamento

​Tratamento de erros

​Valores em centavos

​Boas práticas de segurança