# 3DS Beehive
Source: https://docs.beehivehub.io/3DS-Beehive
Passo a passo para autenticação 3DS.
***
# 🔒 Autenticação 3DS
Ao processar transações com cartão de crédito, a autenticação 3DS adiciona uma camada extra de segurança, reduzindo riscos de fraude e aumentando a aprovação das transações.
O fluxo correto é:
1. Importar o script de autenticação 3DS no front-end
2. Configurar a chave pública da empresa
3. Verificar se o 3DS está disponível
4. Realizar a autenticação 3DS
5. Tokenizar os dados do cartão
6. Enviar o token para o back-end criar a transação
Esse processo garante conformidade com padrões de segurança e protege dados sensíveis.
***
## Setup da biblioteca
Adicione o script da Beehive no `` da sua página:
```html theme={null}
```
***
## Configuração inicial
Antes de qualquer operação, configure o SDK da Beehive.
```javascript theme={null}
// Inicialização do SDK Beehive
const BeehivePay = HopyPay;
// Configure com a chave pública da sua empresa
BeehivePay.setPublicKey("pk_live_sua_chave_publica");
```
***
## Validação do 3DS
Antes de autenticar, verifique se o 3DS está habilitado:
```javascript theme={null}
const is3DSAvailable = await BeehivePay.is3DSAvailable();
console.log("3DS disponível:", is3DSAvailable); // true ou false
```
***
## Autenticação 3DS
Se o 3DS estiver disponível, execute a autenticação:
```javascript theme={null}
const card = {
number: "4111111111111111",
holderName: "Bruce Wayne",
expMonth: 5,
expYear: 2028,
cvv: "123",
};
if (is3DSAvailable) {
await BeehivePay.authenticate3DS({
amount: 4990, // valor em centavos
currency: "brl", // sempre "brl"
installments: 2, // número de parcelas
card,
});
}
```
***
## Tokenização
Após a autenticação, gere o token do cartão:
```javascript theme={null}
const token = await BeehivePay.encrypt({
number: "4111111111111111",
holderName: "Bruce Wayne",
expMonth: 5,
expYear: 2028,
cvv: "123",
});
console.log("Token:", token);
```
***
## 🚀 Envio da transação
No seu servidor, envie o token gerado para criar a transação via API, garantindo que a autenticação 3DS foi realizada com sucesso.
# Beehive + Adoorei
Source: https://docs.beehivehub.io/Beehive-Adoorei
Passo a passo para integrar a Beehive Pay à plataforma Adoorei.
# Beehive + Adoorei
## 1) Pegar sua chave na Adoorei
1. No menu da **Adoorei**, acesse **Configurações → Credenciais de API**.
2. **Copie a Chave Secreta**.
## 2) Instalar e configurar a Beehive Pay na Adoorei
1. Vá em **Apps**.
2. Selecione **Beehive Pay**.
3. **Cole a Chave Secreta**.
4. **Defina suas regras de pagamento**.
> ⚠️ Importante: **não ative** a opção **“Utilizar taxa de juros customizada”**.
## 3) Ativar a integração
1. Altere o status para **ATIVO**.
2. Clique em **SALVAR**.
✅ Integração concluída. Sua loja está pronta para vender via Beehive.
# Beehive + Alphazz
Source: https://docs.beehivehub.io/Beehive-Alphazz
Passo a passo para integrar a Beehive Pay à plataforma Alphazz.
# Beehive + Alphazz
## 1) Pegar suas chaves na Beehive
No painel da Beehive, acesse:
**Configurações → Credenciais de API**
Copie:
* **Chave privada (secreta)**
* **Chave pública**
> ⚠️ Não compartilhe essas chaves. Se vazar, é igual deixar a porta da loja aberta.
***
## 2) Configurar o gateway no Alphazz
No **Alphazz Checkout**, acesse:
**Menu Gateways → Beehive**
Preencha:
* **Chave privada** (cole a chave privada/secreta da Beehive)
* **Chave pública** (cole a chave pública da Beehive)
***
## 3) Ativar e salvar
* Deixe o status como **Ativo**
* Clique em **Salvar**
✅ Integração concluída. Seu Alphazz já está pronto para processar pagamentos via Beehive.
# Beehive + Luna
Source: https://docs.beehivehub.io/Beehive-Luna
Passo a passo para integrar a Beehive Pay ao Luna Checkout.
# Beehive + Luna
## 1) Pegar suas chaves na Beehive
1. Acesse **Beehive → Configurações → Credenciais de API**.
2. Copie a **Chave Pública**.
3. Clique em **Revelar chave** para ver a **Chave Secreta**.
4. Digite o **código enviado por e-mail** e copie a chave.
5. Salve **Chave Pública + Chave Secreta** em um local seguro.
## 2) Conectar a Beehive na Luna
1. Acesse **Luna Checkout → Configurações → Gateways**.
2. Selecione **PayBeehive**.
3. Cole primeiro a **Chave Secreta** e depois a **Chave Pública**.
4. Clique em **Salvar**.
## 3) Configurar pagamentos (Cartão e/ou Pix)
1. Vá em **Checkout → Pagamentos**.
2. Habilite **Cartão** e/ou **Pix**.
3. Em cada método, selecione **PayBeehive** como gateway.
> 💡 Dica: se quiser **repassar juros do parcelamento**, configure as taxas nas opções de cartão.
✅ Integração concluída.
# Beehive + Zedy
Source: https://docs.beehivehub.io/Beehive-Zedy
Passo a passo para integrar a Beehive Pay ao Zedy Checkout.
# Beehive + Zedy
## 1) Pegar suas chaves na Beehive
1. Acesse **Beehive → Configurações → Credenciais de API**.
2. Copie a **Chave Pública**.
3. Clique em **Revelar chave de API** para ver a **Chave Secreta**.
4. Digite o **código enviado por e-mail**.
5. Copie e salve **as duas chaves**.
## 2) Conectar a Beehive na Zedy
1. Acesse **Zedy Checkout → Gateways**.
2. Selecione **Beehive Pay**.
3. Cole primeiro a **Chave Secreta** e depois a **Chave Pública**.
4. Marque o status como **Ativo**.
5. Clique em **Ativar Integração**.
> 💡 Dica: se quiser **repassar juros do parcelamento**, configure as taxas nas opções de cartão.
✅ Integração concluída.
# Obter saldo disponível
Source: https://docs.beehivehub.io/api-reference/balance/get-balance
/api-reference/openapi.yaml get /balance
Retorna o saldo disponível e bloqueado da conta.
# Adicionar conta bancária
Source: https://docs.beehivehub.io/api-reference/bank-accounts/add-bank-account
/api-reference/openapi.yaml post /recipients/{recipientId}/bank-accounts
Para alterar a conta bancária principal de um recebedor, você deve adicionar uma nova conta bancária para ele usando esse endpoint.
# Buscar conta bancária por ID
Source: https://docs.beehivehub.io/api-reference/bank-accounts/get-bank-account
/api-reference/openapi.yaml get /recipients/{recipientId}/bank-accounts/{bankAccountId}
Retorna os detalhes de uma conta bancária específica vinculada a um recebedor (`recipientId`).
# Buscar contas bancárias
Source: https://docs.beehivehub.io/api-reference/bank-accounts/list-bank-accounts
/api-reference/openapi.yaml get /recipients/{recipientId}/bank-accounts
Lista as contas bancárias vinculadas a um recebedor (`recipientId`).
# Dados da empresa
Source: https://docs.beehivehub.io/api-reference/company/get-company
/api-reference/openapi.yaml get /company
Para operações da empresa use a rota /company
# Atualizar dados da empresa
Source: https://docs.beehivehub.io/api-reference/company/update-company
/api-reference/openapi.yaml put /company
# Criar cliente
Source: https://docs.beehivehub.io/api-reference/customers/create-customer
/api-reference/openapi.yaml post /customers
Permite que você crie um novo cliente para a sua loja.
# Buscar cliente
Source: https://docs.beehivehub.io/api-reference/customers/get-customer
/api-reference/openapi.yaml get /customers/{customerId}
Retorna os dados completos de um cliente pelo `customerId`.
# Listar clientes
Source: https://docs.beehivehub.io/api-reference/customers/list-customers
/api-reference/openapi.yaml get /customers
Lista clientes filtrando por email.
**Obs:** neste ambiente o parâmetro `email` é obrigatório.
# Referência da API
Source: https://docs.beehivehub.io/api-reference/introduction
Visão geral da API Beehive Pay — autenticação, base URL e formato de respostas.
## Base URL
Todos os endpoints utilizam a seguinte URL base:
```
https://api.conta.paybeehive.com.br/v1
```
## Autenticação
A API utiliza **Basic Access Authentication**. Você deve enviar sua **chave secreta** codificada em Base64 no header `Authorization`.
```
Authorization: Basic
```
> A senha é sempre `x` — não é utilizada, mas é exigida pelo padrão Basic Auth.
**Onde encontrar sua chave secreta:**
Acesse [Configurações → Credenciais de API](https://app.conta.paybeehive.com.br/settings/credentials) ou clique em **Credenciais** no canto superior direito.
## Formato das respostas
Todas as respostas são retornadas em **JSON**.
```json theme={null}
{
"id": 12345,
"status": "paid",
"amount": 500
}
```
## Códigos de status HTTP
| Código | Significado |
| ------ | -------------------------------------------- |
| `200` | Sucesso |
| `400` | Requisição inválida |
| `401` | Não autorizado — verifique sua chave secreta |
| `404` | Recurso não encontrado |
| `500` | Erro interno do servidor |
## Endpoints disponíveis
Explore os endpoints organizados por recurso no menu lateral:
* **Transações** — criar, listar e buscar transações (cartão, Pix e boleto)
* **Reembolsos** — estornar transações
* **Clientes** — criar, listar e buscar clientes
* **Transferências** — criar e consultar transferências
* **Saldo** — consultar saldo disponível
* **Recebedores** — criar e consultar recebedores
* **Contas Bancárias** — adicionar e consultar contas bancárias
* **Empresa** — consultar e atualizar dados da empresa
* **Payment Links** — criar e atualizar payment links
* **Webhooks** — modelo de payloads dos eventos
# Criar links de pagamento
Source: https://docs.beehivehub.io/api-reference/payment-links/create-payment-link
/api-reference/openapi.yaml post /payment-links
Cria um novo link de pagamento com valor, título e configurações de pagamento.
# Excluir link de pagamento
Source: https://docs.beehivehub.io/api-reference/payment-links/delete-payment-link
/api-reference/openapi.yaml delete /payment-links/{paymentLinkId}
Exclui um link de pagamento existente.
# Buscar link de pagamento por ID
Source: https://docs.beehivehub.io/api-reference/payment-links/get-payment-link
/api-reference/openapi.yaml get /payment-links/{paymentLinkId}
Retorna os detalhes de um link de pagamento específico.
# Buscar links de pagamento
Source: https://docs.beehivehub.io/api-reference/payment-links/list-payment-links
/api-reference/openapi.yaml get /payment-links
Retorna a lista de links de pagamento cadastrados.
# Atualizar link de pagamento
Source: https://docs.beehivehub.io/api-reference/payment-links/update-payment-link
/api-reference/openapi.yaml put /payment-links/{paymentLinkId}
Atualiza um link de pagamento existente.
# Criar recebedor
Source: https://docs.beehivehub.io/api-reference/recipients/create-recipient
/api-reference/openapi.yaml post /recipients
Cria um recebedor (recipient) para receber valores via split/repasse.
# Buscar recebedor
Source: https://docs.beehivehub.io/api-reference/recipients/get-recipient
/api-reference/openapi.yaml get /recipients/{recipientId}
# Listar recebedores
Source: https://docs.beehivehub.io/api-reference/recipients/list-recipients
/api-reference/openapi.yaml get /recipients
# Atualizar recebedor
Source: https://docs.beehivehub.io/api-reference/recipients/update-recipient
/api-reference/openapi.yaml put /recipients/{recipientId}
# Estornar transação
Source: https://docs.beehivehub.io/api-reference/refunds/refund-transaction
/api-reference/openapi.yaml post /transactions/{transactionId}/refund
Cria um estorno para uma transação existente.
# Criar transação
Source: https://docs.beehivehub.io/api-reference/transactions/create-transaction
/api-reference/openapi.yaml post /transactions
Cria uma transação (cartão de crédito, Pix ou boleto).
# Buscar transação
Source: https://docs.beehivehub.io/api-reference/transactions/get-transaction
/api-reference/openapi.yaml get /transactions/{transactionId}
Retorna os detalhes completos de uma transação pelo seu `transactionId`.
# Listar transações
Source: https://docs.beehivehub.io/api-reference/transactions/list-transactions
/api-reference/openapi.yaml get /transactions
Lista transações com filtros.
# Criar transferência
Source: https://docs.beehivehub.io/api-reference/transfers/create-transfer
/api-reference/openapi.yaml post /transfers
Cria uma transferência para um recebedor.
# Buscar transferência
Source: https://docs.beehivehub.io/api-reference/transfers/get-transfer
/api-reference/openapi.yaml get /transfers/{transferId}
Retorna os detalhes de uma transferência pelo `transferId`.
# Exemplo de payload de webhook
Source: https://docs.beehivehub.io/api-reference/webhooks/webhook-event
/api-reference/openapi.yaml post /webhooks/events
Endpoint ilustrativo (documentação do payload). Não é para ser chamado pelo cliente.
# Autenticação
Source: https://docs.beehivehub.io/authentication
## 🔐Como funciona o campo authorization na nossa API.
A nossa API usa **Basic Access Authentication**.
Traduzindo: você autentica enviando sua **chave secreta** codificada em **Base64**, dentro do header HTTP chamado **authorization**.
### **🤔 O que isso significa na prática?**
```
Basic
```
No nosso caso:
* **username** → é a **sua chave secreta** (SECRET\_KEY)
* **password** → é sempre "x"
* Não é usado para nada, mas precisa existir por padrão do Basic Auth.
Ou seja, você precisa montar a string:
`SECRET_KEY:x`
E depois converter isso para Base64.
### **🧠 Exemplo real explicado passo a passo**
**Configurações → Credenciais de API → Chave secreta**
1. Monte a string assim:
```json theme={null}
minha_chave_secreta_aqui:x
```
1. Converta para base64:
```json theme={null}
bWluaGFfY2hhdmVfc2VjcmV0YV9hcXVpOng=
```
1. Envie no header:
```json theme={null}
authorization: Basic bWluaGFfY2hhdmVfc2VjcmV0YV9hcXVpOng=
```
### **🟧 Exemplo em Node.js atualizado**
```bash theme={null}
const options = {
method: "POST",
url: "https://api.conta.paybeehive.com.br/v1/transactions",
headers: {
authorization: "Basic " + Buffer.from(`${SECRET_KEY}:x`).toString("base64"),
"Content-Type": "application/json"
},
body: JSON.stringify({
/* payload da transação */
})
};
```
## **Onde pegar sua chave secreta 🧭**
No painel da Beehive:
**Configurações → Credenciais de API**
Ali você verá:
* 🔑 **Chave secreta**
* 🔓 **Chave pública** (para uso client-side, não serve para autenticar na API)
* ⏳ Prazo de expiração da chave
A **chave secreta** é a que você deve usar no Basic Auth.
# Entrando em Produção
Source: https://docs.beehivehub.io/development
Preview changes locally to update your docs
# Entrando em Produção
### 1. 🚀 Acesse o Ambiente de Produção
Acesse [https://app.conta.paybeehive.com.br/settings/company](https://app.conta.paybeehive.com.br/settings/company) e siga o passo a passo abaixo
***
### 2. 🏢 Preencha o Cadastro Completo
* Insira todos os dados da empresa.
* Informe os dados dos sócios/representantes legais.
* Anexe os documentos obrigatórios:
* 📄 Documentos da empresa (CNPJ, contrato social, etc.)
* 🧑💼 Documentos dos sócios (RG, CPF)
* 🏠 Comprovante de endereço atualizado
* 📂 Outros documentos específicos do segmento, se necessário
***
### 3. 📤 Envio e Validação dos Documentos
* Após anexar todos os documentos, envie para análise.
* Certifique-se de que todos os arquivos estão legíveis e atualizados.
* Mantenha as informações consistentes entre os documentos.
***
### 4. 🔎 Análise e Aprovação
* A equipe responsável fará a análise dos dados e documentos enviados.
* O prazo de resposta costuma ser de até 24 horas úteis.
* Caso haja pendências ou necessidade de documentos adicionais, você será notificado por e-mail ou pela própria plataforma.
***
### 5. ✅ Recebimento da Aprovação
Após aprovação, você receberá um e-mail com a confirmação e instruções para os próximos passos no ambiente de produção.
***
### 6. 💡 Dicas para Aprovação Rápida
* Garanta a legibilidade dos documentos.
* Verifique se todos os dados estão corretos e atualizados.
* Responda rapidamente a eventuais solicitações de complementação.
# Comece por aqui
Source: https://docs.beehivehub.io/index
## **👋 Bem-vindo à nossa documentação de API!**
### 🐝 Como navegar pela documentação
Para facilitar sua jornada, organizamos a documentação em etapas simples e objetivas. Siga cada uma delas para aproveitar ao máximo nossa API!
* **Introdução**: Visão geral e primeiros passos.
* **Autenticação**: Como garantir acesso seguro à API.
* **Tokenização de Cartão de Crédito**: Protegendo dados sensíveis.
* **Entrando em Produção**: Dicas para migrar do ambiente de testes para o real.
* **Webhook**: Automatizando notificações e integrações.
> 📌 Siga cada etapa, e você terá todo o suporte para uma integração de sucesso!
### **Sobre a API**
Nossa API segue os padrões **REST**. Todas as respostas são enviadas no formato **JSON**.
Para autenticar, você deve passar sua **chave secreta** seguindo o padrão [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
### **🔑 Onde encontrar suas chaves**
Acesse o menu:
[Configurações → Credenciais de API](https://app.conta.paybeehive.com.br/settings/credentials)
ou clique no botão localizado no canto superior direito "Credenciais".
Ali você verá:
* **Chave secreta** (para autenticação na API)
* **Chave pública** (uso client-side, não serve para autenticar na API)
# LLMs
Source: https://docs.beehivehub.io/llms-beehive
Como a Beehive disponibiliza contexto estruturado para agentes de IA e ferramentas como Cursor, Claude e ChatGPT.
## O que é o llms.txt?
O `llms.txt` é um arquivo de texto simples que fica na raiz de um site ou documentação e serve como **fonte de contexto para modelos de linguagem (LLMs)**. O conceito é análogo ao `robots.txt` para motores de busca — mas voltado para IAs.
Quando você cola a URL de um `llms.txt` em ferramentas como Cursor, Claude ou ChatGPT, o modelo passa a entender o produto, os endpoints, os padrões de autenticação e as regras de negócio daquela API **sem precisar vasculhar páginas de documentação separadas**.
O padrão foi proposto por [Jeremy Howard](https://llmstxt.org) e vem sendo adotado por fintechs, APIs e ferramentas developer-first ao redor do mundo.
***
## Por que a Beehive tem um?
A API Beehive tem particularidades que costumam gerar erros em integrações assistidas por IA:
* Autenticação com esquema **Bearer + Basic** (base64 de `SECRET_KEY:x`)
* Valores sempre em **centavos** (ex.: `10000` = R\$ 100,00)
* Objeto `metadata` **obrigatório** em toda transação
* QR Code PIX: a API retorna o **texto**, não a imagem — a renderização é responsabilidade do cliente
* Tokenização de cartão **exclusivamente no front-end** (PCI-DSS)
Sem contexto adequado, agentes de IA cometem esses erros com frequência. O `llms.txt` resolve isso: ele reúne em um único arquivo todas as regras, exemplos e orientações específicas para quem está construindo ou gerando código de integração com a Beehive.
***
## Como usar
### No Cursor
Abra o chat do Cursor e cole o link do arquivo como contexto:
```
https://docs.beehivehub.io/llms.txt
```
A partir daí, o Cursor entende os endpoints, campos obrigatórios e padrões da API ao gerar ou revisar código.
### No Claude ou ChatGPT
Inicie sua conversa colando o conteúdo do arquivo ou fornecendo a URL diretamente:
```
Contexto da API: https://docs.beehivehub.io/llms.txt
Com base nisso, me ajude a criar uma transação PIX de R$ 50,00.
```
### Em qualquer agente ou MCP
O arquivo segue o padrão `llms.txt` — compatível com qualquer ferramenta que consuma contexto em texto plano.
***
## Acessar o arquivo
Arquivo de contexto completo da API Beehive para uso em agentes de IA, Cursor, Claude e ChatGPT.
***
# n8n
Source: https://docs.beehivehub.io/n8n
Integre a Beehive com o n8n para automatizar fluxos e criar rotinas.
**O node da BeehiveHub para n8n permite integrar o gateway de pagamentos da plataforma diretamente aos seus fluxos de automação. Com ele, você pode automatizar cobranças, consultar transações, cadastrar clientes, criar transferências, consultar saldo e gerar links de pagamento sem sair do n8n.**
> Esta página mostra como instalar e usar o node. Para detalhes completos dos campos aceitos em cada operação, consulte também a referência da API.
## Instalação
Você pode instalar o node da BeehiveHub via npm em ambientes self-hosted.
Para a instalação do nó, recomendamos que seu n8n self-hosted seja hospedado em um ambiente [Docker](https://docs.n8n.io/hosting/installation/docker/), seguindo a própria documentação do n8n como base
### Via npm
```bash theme={null}
npm install @paybeehive/n8n-nodes-beehivehub
```
***
## Credenciais
Para usar este node, você precisa de uma **BeehiveHub API Secret Key**.
### Como obter sua chave
1. Faça login no dashboard da paybeehive
2. Vá até as configurações da conta ou seção de API Keys
3. Copie sua `Secret Key`
### Como configurar no n8n
1. No n8n, vá em **Credentials**
2. Clique em **Create Credential**
3. Procure por **BeehiveHub API**
4. Cole sua `Secret Key`
5. Clique em **Save**
> O node usa HTTP Basic Auth internamente. A secret key é enviada como usuário, e a senha é ignorada pela API.
***
## Operações disponíveis
### Transaction
* **Create**: cria uma nova transação (`pix`, `boleto` ou `credit_card`)
* **Get**: consulta uma transação por ID
* **Get Many**: lista transações com filtros
* **Refund**: realiza reembolso total ou parcial
* **Update Delivery Status**: atualiza o status de entrega da transação
### Customer
* **Create**: cadastra um novo cliente
* **Get**: consulta um cliente por ID
* **Get Many**: lista clientes
### Transfer
* **Create**: cria uma transferência
* **Get**: consulta uma transferência por ID
### Balance
* **Get Available**: consulta o saldo disponível
### Payment Link
* **Create**: cria um link de pagamento
* **Get**: consulta um link por ID
* **Get Many**: lista todos os links
* **Update**: atualiza um link existente
* **Delete**: remove um link
***
## Como usar
Depois de instalar o pacote e configurar a credencial:
1. Crie ou abra um workflow no n8n
2. Adicione o node **BeehiveHub**
3. Escolha o recurso desejado, como `Transaction`, `Customer`, `Transfer`, `Balance` ou `Payment Link`
4. Selecione a operação
5. Preencha os campos necessários
6. Execute o node para testar a integração
***
## Valores em centavos
Todos os valores monetários devem ser enviados em centavos.
Exemplos:
* `1000` = R\$ 10,00
* `4990` = R\$ 49,90
***
## Métodos de pagamento aceitos
Ao criar uma transação, o campo `paymentMethod` aceita os seguintes valores:
* `pix`
* `boleto`
* `credit_card`
***
## Compatibilidade
* **n8n**: versão mínima `1.0`
* **Node.js**: `v22` ou superior
* **n8n API version**: `1` em modo strict
> O pacote foi testado em n8n self-hosted. A compatibilidade com n8n Cloud depende da verificação de community nodes.
***
## Uso com IA no n8n
Este node é marcado como `usableAsTool`, o que permite utilizá-lo como ferramenta em fluxos com **n8n AI Agent**.
Isso é útil para cenários em que um agente precisa, por exemplo:
* criar uma cobrança automaticamente
* consultar uma transação
* buscar saldo
* gerar um link de pagamento como parte de um fluxo inteligente
***
## Casos de uso
O node da BeehiveHub é indicado para fluxos como:
* receber dados de formulário e gerar cobrança
* consultar pagamentos automaticamente
* cadastrar clientes sem ação manual
* gerar links de pagamento para enviar em outros canais
* integrar a operação financeira com CRM, planilhas, e-mail ou automações internas
***
## Exemplo de fluxo
Um fluxo simples com n8n pode seguir esta lógica:
1. Receber um formulário ou webhook
2. Criar uma transação Pix
3. Armazenar a resposta em uma planilha ou CRM
4. Enviar o link ou QR Code para o cliente
***
## Observações importantes
* Use sempre sua `Secret Key` correta no ambiente desejado
* Revise os campos obrigatórios conforme o recurso selecionado
* Para payloads mais detalhados, combine esta página com a referência da API
* Em transações com cartão, siga o fluxo seguro de tokenização antes do envio para a API
***
## Recursos úteis
* Documentação da API da paybeehive
* Documentação de Community Nodes do n8n
* Fórum da comunidade n8n
# Tokenização de Cartão de Crédito
Source: https://docs.beehivehub.io/quickstart
Quando você cria uma transação usando cartão de crédito, o número do cartão nunca deve ser enviado diretamente para a API.
### O fluxo correto é:
1. **Tokenizar** os dados do cartão no front-end
2. Receber um **token seguro**
3. Enviar esse token na requisição de criação da transação no back-end
Esse processo garante conformidade com **PCI-DSS**, reduz sua superfície de risco e impede que dados sensíveis passem pelo seu servidor.
### **🧩 Incluindo a biblioteca de tokenização**
A tokenização é feita **exclusivamente no front-end**, usando nossa biblioteca JavaScript.
Basta adicionar o script abaixo **no \ da sua página**
```javascript theme={null}
```
Esse script carrega a engine de criptografia responsável por transformar os dados reais do cartão em um token seguro.
### **🔑 Configurando a biblioteca**
Antes de gerar qualquer token, você precisa definir:
* A **chave pública** da sua company (obtida em Configurações → Credenciais de API)
* Se o ambiente está em **modo de teste** ou produção
```json theme={null}
BeehivePay.setPublicKey("SUA_CHAVE_PUBLICA_AQUI");
BeehivePay.setTestMode(true); // Defina false em produção
```
A chave pública **não oferece risco** — ela foi criada exatamente para ser usada no front-end.
### **🪄 Gerando o token do cartão (encrypt)**
Após o cliente digitar os dados do cartão e clicar em finalizar compra, você chama:
```javascript theme={null}
var token = await BeehivePay.encrypt({
number: "4111111111111111",
holderName: "Bruce Wayne",
expMonth: 1,
expYear: 2025,
cvv: "123"
});
```
**O que acontece aqui?**
* Os dados são criptografados diretamente no navegador
* Nenhuma informação sensível trafega pelo seu servidor
* Você recebe algo assim:
```bash theme={null}
bhp_tok_6af98c4e1c6e4f0ab6d93e8e7d093fab
```
Esse token representa o cartão e **pode ser enviado com segurança para o back-end**.
**Precisa de ajuda?** Veja nossa documentação completa ou entre em nossa comunidade.
# Java
Source: https://docs.beehivehub.io/sdk-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`:
```xml theme={null}
br.com.paybeehive
beehivehub-java-sdk
1.0.0
```
**Gradle:**
```gradle theme={null}
implementation 'br.com.paybeehive:beehivehub-java-sdk:1.0.0'
```
## Autenticação
Inicialize o SDK com a sua `SECRET_KEY`:
```java theme={null}
import br.com.paybeehive.sdk.BeehiveHubClient;
BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));
```
## Ambiente Sandbox
Se quiser usar o ambiente de testes:
```java theme={null}
BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"), "sandbox");
```
## Primeiro uso
Exemplo de criação de uma transação Pix:
```java theme={null}
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
```java theme={null}
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
```java theme={null}
ListTransactionsParams params = new ListTransactionsParams();
params.setLimit(50);
params.setOffset(0);
params.setStartDate("2026-01-01T00:00:00");
List transactions = beehive.transactions.list(params);
```
### Buscar transação por ID
```java theme={null}
Transaction transaction = beehive.transactions.get(123456L);
```
### Reembolsar transação
```java theme={null}
// Reembolso total
beehive.transactions.refund(123456L, null);
// Reembolso parcial
beehive.transactions.refund(123456L, 3000L);
```
### Atualizar status de entrega
```java theme={null}
UpdateDeliveryStatusRequest request = new UpdateDeliveryStatusRequest();
request.setStatus("in_transit");
request.setTrackingCode("BR123456789");
beehive.transactions.updateDelivery(123456L, request);
```
***
## Clientes
### Criar cliente
```java theme={null}
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.
```java theme={null}
List customers = beehive.customers.list("cliente@example.com");
```
### Buscar cliente por ID
```java theme={null}
Customer customer = beehive.customers.get(123456L);
```
***
## Transferências
### Criar transferência
```java theme={null}
CreateTransferRequest request = new CreateTransferRequest();
request.setAmount(50000L);
request.setRecipientId(916L);
Transfer transfer = beehive.transfers.create(request);
```
### Buscar transferência por ID
```java theme={null}
Transfer transfer = beehive.transfers.get(123456L);
```
***
## Saldo
### Consultar saldo
```java theme={null}
Balance balance = beehive.balance.get();
System.out.println("Available: BRL " + balance.getAmount() / 100.0);
System.out.println("Recipient ID: " + balance.getRecipientId());
```
***
## Recebedores
### Criar recebedor
```java theme={null}
CreateRecipientRequest request = new CreateRecipientRequest();
request.setLegalName("Recebedor Teste Ltda");
Recipient recipient = beehive.recipients.create(request);
```
### Listar recebedores
```java theme={null}
List recipients = beehive.recipients.list();
```
### Buscar recebedor por ID
```java theme={null}
Recipient recipient = beehive.recipients.get(916L);
```
### Atualizar recebedor
```java theme={null}
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
```java theme={null}
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
```java theme={null}
List accounts = beehive.bankAccounts.list(916L);
```
***
## Empresa
### Consultar dados da empresa
```java theme={null}
Company company = beehive.company.get();
```
### Atualizar dados da empresa
```java theme={null}
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
```java theme={null}
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.
```java theme={null}
List paymentLinks = beehive.paymentLinks.list();
```
### Buscar link de pagamento por ID
```java theme={null}
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.
```java theme={null}
UpdatePaymentLinkRequest request = new UpdatePaymentLinkRequest();
request.setTitle("Link Atualizado");
request.setAmount(2000L);
PaymentLink updated = beehive.paymentLinks.update(247L, request);
```
### Excluir link de pagamento
```java theme={null}
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:
```java theme={null}
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.
```java theme={null}
// 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
```java theme={null}
// Defina a variável de ambiente: BEEHIVE_SECRET_KEY=your_secret_key_here
BeehiveHubClient beehive = new BeehiveHubClient(System.getenv("BEEHIVE_SECRET_KEY"));
```
# Node.js
Source: https://docs.beehivehub.io/sdk-nodejs
SDK oficial para integração com a API do Beehive Hub. Aceite pagamentos de forma simples e rápida.
## Instalação
```bash theme={null}
npm install @paybeehive/beehivehub-nodejs-sdk
```
## Autenticação
Inicialize o SDK com a sua `SECRET_KEY`:
```typescript theme={null}
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";
const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);
```
## Ambiente Sandbox
Se quiser usar o ambiente de testes:
```typescript theme={null}
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";
const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!, {
environment: "sandbox",
});
```
## Primeiro uso
Exemplo de criação de uma transação Pix:
```typescript theme={null}
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";
const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);
async function criarTransacao() {
const response = await 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",
},
});
return response;
}
```
## 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
```typescript theme={null}
const transaction = await 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
```typescript theme={null}
const transactions = await beehive.transactions.list({
limit: 50,
offset: 0,
createdFrom: "2026-01-01T00:00:00",
})
```
### Buscar transação por ID
```typescript theme={null}
const transaction = await beehive.transactions.get(123456);
```
### Reembolsar transação
```typescript theme={null}
const fullRefund = await beehive.transactions.refund(123456);
const partialRefund = await beehive.transactions.refund(123456, 3000);
```
### Atualizar status de entrega
```typescript theme={null}
const delivery = await beehive.transactions.updateDelivery(123456, {
status: "in_transit",
trackingCode: "BR123456789",
});
```
***
## Clientes
### Criar cliente
```typescript theme={null}
const customer = await 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.
```typescript theme={null}
const customers = await beehive.customers.list({
email: "cliente@example.com",
});
```
### Buscar cliente por ID
```typescript theme={null}
const customers = await beehive.customers.list({
email: "cliente@example.com",
});
```
***
## Transferências
### Criar transferência
```typescript theme={null}
const transfer = await beehive.transfers.create({
amount: 50000,
recipientId: 916,
});
```
### Criar transferência com conta bancária
```typescript theme={null}
const transferWithAccount = await 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
```typescript theme={null}
const transfer = await beehive.transfers.get(123456);
```
***
## Saldo
### Consultar saldo
```typescript theme={null}
const balance = await beehive.balance.get();
console.log(`Available: BRL ${balance.amount / 100}`);
console.log(`Recipient ID: ${balance.recipientId}`);
```
***
## Recebedores
### Criar recebedor
```typescript theme={null}
const recipient = await 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
```typescript theme={null}
const recipients = await beehive.recipients.list();
```
### Buscar recebedor por ID
```typescript theme={null}
const recipient = await beehive.recipients.get(916);
```
### Atualizar recebedor
```typescript theme={null}
const updated = await beehive.recipients.update(916, {
legalName: "Beehive Sandbox",
});
```
***
## Contas bancárias
### Adicionar conta bancária a um recebedor
```typescript theme={null}
const bankAccount = await 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
```typescript theme={null}
const accounts = await beehive.bankAccounts.list(916);
```
***
## Empresa
### Consultar dados da empresa
```typescript theme={null}
const company = await beehive.company.get();
```
### Atualizar dados da empresa
```typescript theme={null}
const updated = await 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
```typescript theme={null}
const paymentLink = await 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.
```typescript theme={null}
const paymentLinks = await beehive.paymentLinks.list();
```
### Buscar link de pagamento por ID
```typescript theme={null}
const paymentLink = await 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.
```typescript theme={null}
const updated = await 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
```text theme={null}
await 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:
```typescript theme={null}
import BeehiveHub, {
BeehiveHubAPIError,
BeehiveHubAuthenticationError,
BeehiveHubValidationError,
} from "@paybeehive/beehivehub-nodejs-sdk";
const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);
try {
const transaction = await beehive.transactions.create({
amount: 10000,
paymentMethod: "pix",
customer: {
name: "João Silva",
email: "joao@example.com",
document: {
type: "cpf",
number: "12345678900",
},
phone: "11999999999",
},
});
console.log("Transaction created:", transaction);
} catch (error) {
if (error instanceof BeehiveHubAuthenticationError) {
console.error("Invalid API key:", error.message);
} else if (error instanceof BeehiveHubValidationError) {
console.error("Validation error:", error.message);
} else if (error instanceof BeehiveHubAPIError) {
console.error("API error:", error.message);
} else {
console.error("Unexpected error:", error);
}
}
```
***
## Valores em centavos
Todos os valores monetários enviados para a API devem ser informados em centavos.
```typescript theme={null}
// R$ 100,00
amount: 10000;
// R$ 1,50
amount: 150;
// Convertendo reais para centavos
const reais = 100.0;
const cents = Math.round(reais * 100);
```
***
## Boas práticas de segurança
* Nunca exponha sua `SECRET_KEY`
* Não gere `card_hash` no backend
* Valide os dados antes de enviar para a API
* Use HTTPS
* Implemente webhooks para acompanhar mudanças de status
```text theme={null}
// .env
BEEHIVE_SECRET_KEY=your_secret_key_here
```
```typescript theme={null}
// app.ts
import BeehiveHub from "@paybeehive/beehivehub-nodejs-sdk";
import dotenv from "dotenv";
dotenv.config();
const beehive = BeehiveHub(process.env.BEEHIVE_SECRET_KEY!);
```
***
# Introdução
Source: https://docs.beehivehub.io/sdk-overview
Bibliotecas oficiais da BeehiveHub para integração com a API
Os SDKs oficiais da BeehiveHub são bibliotecas que facilitam a integração com a nossa API em aplicações backend.
Em vez de montar manualmente chamadas HTTP, headers de autenticação, tratamento de erros e estrutura de requisições, você utiliza métodos prontos para criar transações, consultar clientes, gerar links de pagamento, fazer transferências e acessar outros recursos da plataforma.
## Por que usar um SDK?
O SDK foi criado para tornar a integração mais rápida, organizada e segura.
Ao utilizar o SDK, você reduz a complexidade da implementação porque:
* não precisa montar requisições manualmente para cada endpoint;
* centraliza a autenticação com a sua `SECRET_KEY`;
* trabalha com métodos mais diretos e fáceis de manter;
* reduz a chance de erro na integração;
* acelera a implementação dos recursos mais comuns da API.
## Quando faz sentido usar?
O SDK é indicado quando você possui uma aplicação backend e quer integrar a BeehiveHub no seu servidor, API própria, painel administrativo, backoffice ou backend de e-commerce.
Exemplos de uso:
* criação de transações Pix, boleto e cartão;
* consulta de transações e clientes;
* criação de recebedores e transferências;
* geração de links de pagamento;
* automações internas do seu sistema financeiro.
> Recomendamos o uso dos SDKs para integrações **server-side**. Nunca utilize sua `SECRET_KEY` no front-end.
## Escolha sua linguagem
SDK oficial para aplicações Node.js e TypeScript.
SDK oficial para aplicações PHP.
SDK oficial para aplicações Python.
SDK oficial para aplicações Java.
## Perguntas Frequentes
Cada SDK possui uma página dedicada com as instruções de instalação. De forma geral, utilize o gerenciador de pacotes da sua linguagem:
* **Node.js:** `npm install @paybeehive/beehivehub-nodejs-sdk`
* **PHP:** `composer require paybeehive/beehivehub-php-sdk`
* **Python:** `pip install beehivehub-python-sdk`
* **Java:** via Maven ou Gradle — veja a [página do SDK Java](/sdk-java)
Sim. Todos os SDKs suportam os dois ambientes. Para usar o ambiente de testes, passe `environment: "sandbox"` ao inicializar o cliente. Para produção, basta não informar o parâmetro ou usar a chave da conta de produção.
O uso do SDK é recomendado, mas opcional. Você pode integrar diretamente pela API REST usando qualquer cliente HTTP. A vantagem do SDK é eliminar a configuração manual de autenticação, tratamento de erros e estrutura das requisições.
Abra uma issue no repositório GitHub do SDK correspondente. Nossa equipe acompanha os repositórios e trabalha para corrigir problemas e evoluir os SDKs continuamente.
# PHP
Source: https://docs.beehivehub.io/sdk-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
```bash theme={null}
composer require paybeehive/beehivehub-php-sdk
```
## Autenticação
Inicialize o SDK com a sua `SECRET_KEY`:
```php theme={null}
use BeehiveHub\SDK\BeehiveHubClient;
$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);
```
## Ambiente Sandbox
Se quiser usar o ambiente de testes:
```php theme={null}
use BeehiveHub\SDK\BeehiveHubClient;
$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY'], [
'environment' => 'sandbox',
]);
```
## Primeiro uso
Exemplo de criação de uma transação Pix:
```php theme={null}
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
```php theme={null}
$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
```php theme={null}
$transactions = $beehive->transactions->list([
'limit' => 50,
'offset' => 0,
'createdFrom' => '2026-01-01T00:00:00',
]);
```
### Buscar transação por ID
```php theme={null}
$transaction = $beehive->transactions->get(123456);
```
### Reembolsar transação
```php theme={null}
// Reembolso total
$fullRefund = $beehive->transactions->refund(123456);
// Reembolso parcial
$partialRefund = $beehive->transactions->refund(123456, 3000);
```
### Atualizar status de entrega
```php theme={null}
$delivery = $beehive->transactions->updateDelivery(123456, [
'status' => 'in_transit',
'trackingCode' => 'BR123456789',
]);
```
***
## Clientes
### Criar cliente
```php theme={null}
$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.
```php theme={null}
$customers = $beehive->customers->list([
'email' => 'cliente@example.com',
]);
```
### Buscar cliente por ID
```php theme={null}
$customer = $beehive->customers->get(123456);
```
***
## Transferências
### Criar transferência
```php theme={null}
$transfer = $beehive->transfers->create([
'amount' => 50000,
'recipientId' => 916,
]);
```
### Criar transferência com conta bancária
```php theme={null}
$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
```php theme={null}
$transfer = $beehive->transfers->get(123456);
```
***
## Saldo
### Consultar saldo
```php theme={null}
$balance = $beehive->balance->get();
echo 'Available: BRL ' . ($balance['amount'] / 100) . PHP_EOL;
echo 'Recipient ID: ' . $balance['recipientId'] . PHP_EOL;
```
***
## Recebedores
### Criar recebedor
```php theme={null}
$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
```php theme={null}
$recipients = $beehive->recipients->list();
```
### Buscar recebedor por ID
```php theme={null}
$recipient = $beehive->recipients->get(916);
```
### Atualizar recebedor
```php theme={null}
$updated = $beehive->recipients->update(916, [
'legalName' => 'Beehive Sandbox',
]);
```
***
## Contas bancárias
### Adicionar conta bancária a um recebedor
```php theme={null}
$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
```php theme={null}
$accounts = $beehive->bankAccounts->list(916);
```
***
## Empresa
### Consultar dados da empresa
```php theme={null}
$company = $beehive->company->get();
```
### Atualizar dados da empresa
```php theme={null}
$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
```php theme={null}
$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.
```php theme={null}
$paymentLinks = $beehive->paymentLinks->list();
```
### Buscar link de pagamento por ID
```php theme={null}
$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.
```php theme={null}
$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
```php theme={null}
$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:
```php theme={null}
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.
```php theme={null}
// 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
```text theme={null}
# .env
BEEHIVE_SECRET_KEY=your_secret_key_here
```
```php theme={null}
// bootstrap.php
use BeehiveHub\SDK\BeehiveHubClient;
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$beehive = new BeehiveHubClient($_ENV['BEEHIVE_SECRET_KEY']);
```
***
# Python
Source: https://docs.beehivehub.io/sdk-python
SDK oficial para integração com a API do Beehive Hub. Aceite pagamentos de forma simples e rápida.
## Requisitos
* Python 3.10 ou superior
* Dependências instaladas automaticamente: `httpx` e `pydantic`
## Instalação
```bash theme={null}
pip install beehivehub-python-sdk
```
## Autenticação
Inicialize o SDK com a sua `SECRET_KEY`:
```python theme={null}
import os
from beehivehub import create_beehivehub_client
beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])
```
## Ambiente Sandbox
Se quiser usar o ambiente de testes:
```python theme={null}
import os
from beehivehub import create_beehivehub_client
beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"], environment="sandbox")
```
## Primeiro uso
Exemplo de criação de uma transação Pix:
```python theme={null}
import os
from beehivehub import create_beehivehub_client
beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])
transaction = 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`
* `bank_accounts`
* `company`
* `payment_links`
***
## Transações
### Criar transação
```python theme={null}
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
```python theme={null}
transactions = beehive.transactions.list({
"status": "paid",
"paymentMethods": "pix",
})
```
### Buscar transação por ID
```python theme={null}
transaction = beehive.transactions.get(123456)
```
### Reembolsar transação
```python theme={null}
full_refund = beehive.transactions.refund(123456)
partial_refund = beehive.transactions.refund(123456, 3000)
```
### Atualizar status de entrega
```python theme={null}
delivery = beehive.transactions.update_delivery(123456, {
"status": "in_transit",
"trackingCode": "BR123456789",
})
```
***
## Clientes
### Criar cliente
```python theme={null}
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.
```python theme={null}
customers = beehive.customers.list({
"email": "cliente@example.com",
})
```
### Buscar cliente por ID
```python theme={null}
customer = beehive.customers.get(123456)
```
***
## Transferências
### Criar transferência
```python theme={null}
transfer = beehive.transfers.create({
"amount": 50000,
"recipientId": 916,
})
```
### Criar transferência com conta bancária
```python theme={null}
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
```python theme={null}
transfer = beehive.transfers.get(123456)
```
***
## Saldo
### Consultar saldo
```python theme={null}
balance = beehive.balance.get()
print(f"Available: BRL {balance['amount'] / 100}")
print(f"Recipient ID: {balance['recipientId']}")
```
***
## Recebedores
### Criar recebedor
```python theme={null}
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
```python theme={null}
recipients = beehive.recipients.list()
```
### Buscar recebedor por ID
```python theme={null}
recipient = beehive.recipients.get(916)
```
### Atualizar recebedor
```python theme={null}
updated = beehive.recipients.update(916, {
"legalName": "Beehive Sandbox",
})
```
***
## Contas bancárias
### Adicionar conta bancária a um recebedor
```python theme={null}
bank_account = beehive.bank_accounts.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
```python theme={null}
accounts = beehive.bank_accounts.list(916)
```
***
## Empresa
### Consultar dados da empresa
```python theme={null}
company = beehive.company.get()
```
### Atualizar dados da empresa
```python theme={null}
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
```python theme={null}
payment_link = beehive.payment_links.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,
},
},
})
# payment_link["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.
```python theme={null}
payment_links = beehive.payment_links.list()
```
### Buscar link de pagamento por ID
```python theme={null}
payment_link = beehive.payment_links.get(247)
```
### Atualizar link de pagamento
> A atualização aceita payload parcial, ou seja, você pode enviar apenas os campos que deseja alterar.
```python theme={null}
updated = beehive.payment_links.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
```python theme={null}
beehive.payment_links.delete(247)
```
***
## Tratamento de erros
O SDK expõe classes específicas para tratamento de erro:
* `BeehiveHubAPIError`
* `BeehiveHubAuthenticationError`
* `BeehiveHubValidationError`
* `BeehiveHubNotFoundError`
* `BeehiveHubRateLimitError`
* `BeehiveHubNetworkError`
Exemplo:
```python theme={null}
import os
from beehivehub import (
create_beehivehub_client,
BeehiveHubAPIError,
BeehiveHubAuthenticationError,
BeehiveHubValidationError,
)
beehive = create_beehivehub_client(os.environ["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",
},
})
print("Transaction created:", transaction)
except BeehiveHubAuthenticationError as e:
print(f"Invalid API key: {e}")
except BeehiveHubValidationError as e:
print(f"Validation error: {e}")
except BeehiveHubAPIError as e:
print(f"API error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
```
***
## Valores em centavos
Todos os valores monetários enviados para a API devem ser informados em centavos.
```python theme={null}
# R$ 100,00
amount = 10000
# R$ 1,50
amount = 150
# Convertendo reais para centavos
reais = 100.0
cents = round(reais * 100)
```
***
## Boas práticas de segurança
* Nunca exponha sua `SECRET_KEY`
* Não gere `card_hash` no backend
* Valide os dados antes de enviar para a API
* Use HTTPS
* Implemente webhooks para acompanhar mudanças de status
```text theme={null}
# .env
BEEHIVE_SECRET_KEY=your_secret_key_here
```
```python theme={null}
# app.py
import os
from dotenv import load_dotenv
from beehivehub import create_beehivehub_client
load_dotenv()
beehive = create_beehivehub_client(os.environ["BEEHIVE_SECRET_KEY"])
```
***
# Webhook
Source: https://docs.beehivehub.io/webhook
# 🔄 Webhooks
Sempre que uma transação, checkout ou transferência muda de status, a Beehive envia automaticamente uma **notificação HTTP (POST)** para a URL que você informar no campo postbackUrl.
Essa URL deve ser um endpoint do seu sistema capaz de:
* receber JSON via POST
* validar e armazenar o evento
* processar atualizações conforme sua lógica de negócio
Os postbacks permitem que seu sistema seja atualizado **em tempo real**, sem precisar ficar consultando a API.
## 🧩 Estrutura do Payload
Todos os postbacks seguem um formato padrão:
```json theme={null}
{
"id": ,
"type": "",
"objectId": "",
"url": "",
"data": {
/* objeto completo com os detalhes do evento */
}
}
```
O campo data contém todas as informações da transação, checkout ou transferência no momento da atualização.
Abaixo, os 3 formatos completos para cada tipo de evento.
## 🟧 1. Postback de Transação (type: "transaction")
Esse evento é enviado sempre que uma transação muda de status — por exemplo:
* created
* processing
* authorized
* paid
* refused
* refunded
**Exemplo completo:**
```json theme={null}
{
"id": 686401,
"type": "transaction",
"objectId": "282",
"url": "https://test.com",
"data": {
"id": 282,
"amount": 10000,
"refundedAmount": 0,
"companyId": 2,
"installments": 12,
"paymentMethod": "credit_card",
"status": "paid",
"postbackUrl": null,
"metadata": null,
"traceable": false,
"secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
"secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
"createdAt": "2022-07-18T09:54:22.000Z",
"updatedAt": "2022-07-18T09:54:22.000Z",
"paidAt": "2022-07-18T09:54:22.000Z",
"ip": null,
"externalRef": null,
"customer": {
"id": 1,
"externalRef": null,
"name": "Gabryel",
"email": "gabryel@hotmail.com",
"phone": "11999999999",
"birthdate": null,
"createdAt": "2022-05-26T19:17:48.000Z",
"document": {
"number": "12345678910",
"type": "cpf"
},
"address": {
"street": "Rua República Argentina",
"streetNumber": "4214",
"complement": null,
"zipCode": "11065030",
"neighborhood": "Pompéia",
"city": "Santos",
"state": "SP",
"country": "BR"
}
},
"card": {
"id": 147,
"brand": "visa",
"holderName": "GABRYEL FERREIRA",
"lastDigits": "1111",
"expirationMonth": 3,
"expirationYear": 2028,
"reusable": true,
"createdAt": "2022-07-17T18:08:11.000Z"
},
"boleto": null,
"pix": null,
"shipping": null,
"refusedReason": null,
"items": [
{
"externalRef": null,
"title": "b456",
"unitPrice": 100,
"quantity": 1,
"tangible": false
}
],
"splits": [
{
"recipientId": 1,
"amount": 10000,
"netAmount": 9400
}
],
"refunds": [],
"delivery": null,
"fee": {
"fixedAmount": 200,
"spreadPercentage": 4,
"estimatedFee": 600,
"netAmount": 9400
}
}
}
```
## 🟦 2. Postback de Checkout (type: "checkout")
Esse evento é disparado quando um checkout criado via Link de Pagamento é atualizado — por exemplo:
* ativação
* atualização dos itens
* ligação com a transação finalizada
Ele inclui tanto o objeto **checkout** quanto a **transação associada** (se existir).
**Exemplo completo:**
```json theme={null}
{
"id": 686401,
"type": "checkout",
"objectId": "3",
"url": "https://test.com",
"data": {
"id": 3,
"companyId": 2,
"description": null,
"amount": 1000,
"secureId": "019c2702-6fbe-4199-b21c-c9342888d6ec",
"secureUrl": "https://link.compra.com.br/checkout/019c2702-6fbe-4199-b21c-c9342888d6ec",
"postbackUrl": "https://test.com",
"createdAt": "2022-08-02T18:04:04.000Z",
"settings": {
"defaultPaymentMethod": "credit_card",
"requestAddress": false,
"requestPhone": true,
"requestDocument": true,
"traceable": false,
"card": {
"enabled": true,
"freeInstallments": 1,
"maxInstallments": 12
},
"boleto": {
"enabled": false,
"expiresInDays": 2
},
"pix": {
"enabled": true,
"expiresInDays": 2
}
},
"items": [
{
"externalRef": null,
"title": "Hamburgão",
"unitPrice": 3000,
"quantity": 1,
"tangible": true
}
],
"splits": [],
"transaction": {
"id": 282,
"amount": 10000,
"refundedAmount": 0,
"companyId": 2,
"installments": 12,
"paymentMethod": "credit_card",
"status": "paid",
"postbackUrl": null,
"metadata": null,
"traceable": false,
"secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
"secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
"createdAt": "2022-07-18T09:54:22.000Z",
"updatedAt": "2022-07-18T09:54:22.000Z",
"paidAt": "2022-07-18T09:54:22.000Z",
"ip": null,
"externalRef": null,
"customer": {
"id": 1,
"externalRef": null,
"name": "Gabryel",
"email": "gabryel@hotmail.com",
"phone": "11999999999",
"birthdate": null,
"createdAt": "2022-05-26T19:17:48.000Z",
"document": {
"number": "12345678910",
"type": "cpf"
},
"address": {
"street": "Rua República Argentina",
"streetNumber": "4214",
"complement": null,
"zipCode": "11065030",
"neighborhood": "Pompéia",
"city": "Santos",
"state": "SP",
"country": "BR"
}
},
"card": {
"id": 147,
"brand": "visa",
"holderName": "GABRYEL FERREIRA",
"lastDigits": "1111",
"expirationMonth": 3,
"expirationYear": 2028,
"reusable": true,
"createdAt": "2022-07-17T18:08:11.000Z"
},
"boleto": null,
"pix": null,
"shipping": null,
"refusedReason": null,
"items": [
{
"externalRef": null,
"title": "b456",
"unitPrice": 100,
"quantity": 1,
"tangible": false
}
],
"splits": [
{
"recipientId": 1,
"amount": 10000,
"netAmount": 9400
}
],
"refunds": [],
"delivery": null,
"fee": {
"fixedAmount": 200,
"spreadPercentage": 4,
"estimatedFee": 600,
"netAmount": 9400
}
}
}
}
```
## 🟩 3. Postback de Transferência (type: "transfer")
Enviado quando uma transferência (Pix, TED, repasse interno) muda de status.
Alguns exemplos de status:
* bank\_processing
* processed
* failed
* transferred
**Exemplo completo:**
```json theme={null}
{
"id": 388,
"type": "transfer",
"objectId": "237",
"url": "https://test.com",
"data": {
"id": 237,
"amount": 500,
"status": "bank_processing",
"pixKey": "12345678900",
"fee": 0,
"bankAccount": null,
"metadata": null,
"createdAt": "2022-10-18T16:43:42.000Z",
"updatedAt": "2022-10-18T16:43:44.000Z",
"failReason": null,
"receiptUrl": null,
"description": "Transferência Teste",
"externalRef": null,
"postbackUrl": "https://test.com",
"processedAt": "2022-10-18T16:43:44.000Z",
"recipientId": 1,
"pixEnd2EndId": "E277287121G6I8886MF02JNCUGGLELRP",
"transferredAt": null
}
}
```