Java

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

Requisitos

Java 11 ou superior
Maven ou Gradle

Instalação

Maven — adicione ao seu pom.xml:

<dependency>
    <groupId>br.com.paybeehive</groupId>
    <artifactId>beehivehub-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle:

implementation 'br.com.paybeehive:beehivehub-java-sdk:1.0.0'

Autenticação

Inicialize o SDK com a sua SECRET_KEY:

import br.com.paybeehive.sdk.BeehiveHubClient;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

Ambiente Sandbox

Se quiser usar o ambiente de testes:

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"), "sandbox");

Primeiro uso

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

import br.com.paybeehive.sdk.BeehiveHubClient;
import br.com.paybeehive.sdk.models.Transaction;
import br.com.paybeehive.sdk.requests.CreateTransactionRequest;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

CreateTransactionRequest request = new CreateTransactionRequest();
request.setAmount(15990L);
request.setPaymentMethod("pix");
request.setPostbackUrl("https://seusite.com/webhook");

Transaction transaction = beehive.transactions.create(request);
System.out.println("Transação criada: " + transaction.getId());

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

CreateTransactionRequest request = new CreateTransactionRequest();
request.setAmount(8900L);
request.setPaymentMethod("pix");
request.setPostbackUrl("https://seusite.com/webhook");

Transaction transaction = beehive.transactions.create(request);

Listar transações

ListTransactionsParams params = new ListTransactionsParams();
params.setLimit(50);
params.setOffset(0);
params.setStartDate("2026-01-01T00:00:00");

List<Transaction> transactions = beehive.transactions.list(params);

Buscar transação por ID

Transaction transaction = beehive.transactions.get(123456L);

Reembolsar transação

// Reembolso total
beehive.transactions.refund(123456L, null);

// Reembolso parcial
beehive.transactions.refund(123456L, 3000L);

Atualizar status de entrega

UpdateDeliveryStatusRequest request = new UpdateDeliveryStatusRequest();
request.setStatus("in_transit");
request.setTrackingCode("BR123456789");

beehive.transactions.updateDelivery(123456L, request);

Clientes

Criar cliente

import br.com.paybeehive.sdk.models.Address;
import br.com.paybeehive.sdk.models.Document;

Document document = new Document();
document.setType("cpf");
document.setNumber("98765432100");

Address address = new Address();
address.setStreet("Rua Exemplo");
address.setStreetNumber("200");
address.setComplement("Sala 3");
address.setNeighborhood("Centro");
address.setZipCode("01001000");
address.setCity("São Paulo");
address.setState("SP");
address.setCountry("br");

CreateCustomerRequest request = new CreateCustomerRequest();
request.setName("Mariana Costa");
request.setEmail("mariana@email.com");
request.setPhone("11977777777");
request.setDocument(document);
request.setAddress(address);

Customer customer = beehive.customers.create(request);

Listar clientes

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

List<Customer> customers = beehive.customers.list("cliente@example.com");

Buscar cliente por ID

Customer customer = beehive.customers.get(123456L);

Transferências

Criar transferência

CreateTransferRequest request = new CreateTransferRequest();
request.setAmount(50000L);
request.setRecipientId(916L);

Transfer transfer = beehive.transfers.create(request);

Buscar transferência por ID

Transfer transfer = beehive.transfers.get(123456L);

Saldo

Consultar saldo

Balance balance = beehive.balance.get();

System.out.println("Available: BRL " + balance.getAmount() / 100.0);
System.out.println("Recipient ID: " + balance.getRecipientId());

Recebedores

Criar recebedor

CreateRecipientRequest request = new CreateRecipientRequest();
request.setLegalName("Recebedor Teste Ltda");

Recipient recipient = beehive.recipients.create(request);

Listar recebedores

List<Recipient> recipients = beehive.recipients.list();

Buscar recebedor por ID

Recipient recipient = beehive.recipients.get(916L);

Atualizar recebedor

UpdateRecipientRequest request = new UpdateRecipientRequest();
request.setLegalName("Beehive Sandbox");

Recipient updated = beehive.recipients.update(916L, request);

Contas bancárias

Adicionar conta bancária a um recebedor

CreateBankAccountRequest request = new CreateBankAccountRequest();
request.setBankCode("341");
request.setAgencyNumber("9876");
request.setAccountNumber("54321");
request.setAccountDigit("0");
request.setType("conta_poupanca");
request.setLegalName("Empresa Teste Ltda");
request.setDocumentNumber("60572883000136");
request.setDocumentType("cnpj");

BankAccount bankAccount = beehive.bankAccounts.create(916L, request);

Listar contas bancárias

List<BankAccount> accounts = beehive.bankAccounts.list(916L);

Empresa

Consultar dados da empresa

Company company = beehive.company.get();

Atualizar dados da empresa

UpdateCompanyRequest request = new UpdateCompanyRequest();
request.setInvoiceDescriptor("Beehive Hub");

UpdateCompanyRequest.Details details = new UpdateCompanyRequest.Details();
details.setAverageRevenue(10000L);
details.setAverageTicket(100L);
details.setPhysicalProducts(true);
details.setProductsDescription("Produtos físicos");
details.setSiteUrl("https://www.meusite.com.br");
details.setPhone("11999999999");
details.setEmail("contato@meusite.com.br");
request.setDetails(details);

Company updated = beehive.company.update(request);

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

CreatePaymentLinkRequest request = new CreatePaymentLinkRequest();
request.setTitle("Meu Link de Pagamento");
request.setAlias("alias_alterado");
request.setAmount(1000L);

PaymentLink paymentLink = beehive.paymentLinks.create(request);
// paymentLink.getUrl() 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.

List<PaymentLink> paymentLinks = beehive.paymentLinks.list();

Buscar link de pagamento por ID

PaymentLink paymentLink = beehive.paymentLinks.get(247L);

Atualizar link de pagamento

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

UpdatePaymentLinkRequest request = new UpdatePaymentLinkRequest();
request.setTitle("Link Atualizado");
request.setAmount(2000L);

PaymentLink updated = beehive.paymentLinks.update(247L, request);

Excluir link de pagamento

beehive.paymentLinks.delete(247L);

Tratamento de erros

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

BeehiveHubAPIError
BeehiveHubAuthenticationError
BeehiveHubValidationError
BeehiveHubNotFoundError
BeehiveHubRateLimitError
BeehiveHubNetworkError

Exemplo:

import br.com.paybeehive.sdk.BeehiveHubClient;
import br.com.paybeehive.sdk.exceptions.*;

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

try {
    Transaction transaction = beehive.transactions.create(request);
    System.out.println("Transação criada: " + transaction.getId());
} catch (BeehiveHubAuthenticationError e) {
    System.err.println("Chave inválida: " + e.getMessage());
} catch (BeehiveHubValidationError e) {
    System.err.println("Erro de validação: " + e.getMessage());
} catch (BeehiveHubNotFoundError e) {
    System.err.println("Não encontrado: " + e.getMessage());
} catch (BeehiveHubRateLimitError e) {
    System.err.println("Rate limit excedido: " + e.getMessage());
} catch (BeehiveHubAPIError e) {
    System.err.println("Erro na API: " + e.getMessage());
} catch (BeehiveHubNetworkError e) {
    System.err.println("Erro de rede: " + e.getMessage());
}

Valores em centavos

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

// R$ 100,00
request.setAmount(10000L);

// R$ 1,50
request.setAmount(150L);

// Convertendo reais para centavos
double reais = 100.0;
long cents = Math.round(reais * 100); // 10000

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

// Defina a variável de ambiente: BEEHIVE_SECRET_KEY=your_secret_key_here

BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));

Java

​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

​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