# BotaPix
> BotaPix é uma plataforma brasileira de pagamentos via Pix. Desenvolvedores podem integrar uma **API REST** pra gerar cobranças Pix, assinaturas recorrentes (Pix Automático) e receber confirmação de pagamento por webhook. Criadores de conteúdo podem receber doações na live com uma **página pronta** (`/s/usuario`) e widgets pro OBS: alerta de doação (que pode ler toda doação em voz alta, sem custo extra, ou com uma voz de IA escolhida por quem doa), ranking de doadores, metas, maratona (subathon), enquetes e pedido de vídeo pago (Media Share) — sem escrever código e sem expor a chave Pix pessoal. Funciona na Twitch, na Kick, no YouTube e em qualquer plataforma que use OBS ou Streamlabs.
Notas importantes:
- **Autenticação da API:** header `Authorization: Bearer btpx_...`. O vendedor cria várias chaves no dashboard, cada uma com uma permissão (recebimentos, loja, somente leitura ou financeiro).
- **Ambiente de testes:** chaves `btpx_test_` criam cobranças e assinaturas de teste, com simulação de pagamento, expiração e devolução e webhooks de teste. Nenhum dinheiro se move; o código é o mesmo da produção.
- **Valores monetários** trafegam em **centavos** na API (ex.: `1000` = R$ 10,00).
- **Respostas** usam o envelope `{ "data": {...} }`; erros seguem `{ "error": "...", "message": "..." }`, exceto validação (422, com `errors` por campo) e limite de requisições (429, só `message`).
- **Rate limiting por API key** (não por IP): 600 req/min nas criações (`POST /charges` e `POST /subscriptions`), 200 req/min nas consultas e no cancelamento; chaves de teste, 120 req/min.
- **Idempotência:** header opcional `Idempotency-Key` no `POST /charges`, `POST /subscriptions`, `POST /withdrawals` e `POST /charges/{id}/refunds` — mesma key + mesmo corpo devolve o objeto original; corpo diferente dá `422 idempotency_key_reused`; escopado por vendedor.
- **Webhooks (saída):** o vendedor cadastra até 5 endpoints por ambiente e escolhe os eventos de cada um. Famílias: pagamento (`payment.confirmed`, `payment.refunded`, `payment.expired`), assinatura (`subscription.*`), saque (`withdrawal.*`), devolução (`refund.*`), disputa MED (`dispute.*`) e entrega de produto (`delivery.*`); lista completa em [Eventos](https://botapix.com/docs/webhooks/eventos). Assinado com HMAC-SHA256 (`X-BotaPix-Signature`, secret por ambiente), com até 8 tentativas ao longo de ~33h e `X-BotaPix-Event-Id` estável pra deduplicar.
- **Sem exposição de chave Pix:** o pagador nunca vê a chave Pix pessoal do vendedor/streamer — o BotaPix intermedia e credita o saldo, com período de hold configurável antes do saque.
- **Assinaturas** usam Pix Automático (recorrência), com tarifa fixa + percentual por cobrança recorrente e mínimo de R$ 10.
## Taxas e limites (valores públicos, verificados em novembro/2026)
- **Taxa por transação:** 3% sobre cada pagamento confirmado. Sem mensalidade, sem taxa de adesão, sem custo por inatividade.
- **Saque (repasse):** tarifa de 1,5% (mínimo R$ 0,50), deduzida do valor enviado. Saque mínimo de R$ 10,00; até R$ 500,00 o saque é aprovado automaticamente. O saque vai só pra chave Pix do MESMO CPF/CNPJ do titular da conta — repasse pra terceiros não existe, por desenho.
- **Assinaturas (Pix Automático):** R$ 3,50 fixo + 3% por cobrança recorrente; valor mínimo de assinatura R$ 10,00.
- **Vaquinhas (campanhas de arrecadação):** páginas públicas com meta e prazo, mesma taxa de 3%.
- **Integrações de live (setembro/2026):** alertas de sub, bits e raid da Twitch e da Kick no mesmo widget das doações; maratona (subathon) que ganha tempo com Pix, sub e bits; enquetes com Pix; recompensas (link, conteúdo secreto ou cargo no Discord) por doação ou assinatura; controle dos alertas pelo Stream Deck. Nada de dinheiro passa pela Twitch ou pela Kick: só o alerta.
- **Maratona (subathon) com Pix:** widget de cronômetro pro OBS (timer de subathon) que ganha tempo sozinho a cada doação em Pix (padrão: 1 minuto por R$ 1), sub (5 min), 100 bits ou 100 Kicks (1 min) e, se ligado, raid por viewer. Teto de horas opcional, pausa, ajuste manual de tempo e controle pelo painel Ao vivo; o widget mostra a última adição ("+10m · Maria · R$ 10,00") e tem cinco estilos: Relógio, Pílula, Notificação (card translúcido como as notificações de jogo, com anel do tempo), Anel e Faixa (tarja para a parte de baixo da tela). Maratona, meta, enquete, ranking, histórico e músicas têm a opção de fundo translúcido. Vaquinha e assinatura mensal também somam tempo. Sem custo extra além dos 3% por doação. Guia: https://botapix.com/blog/maratona-subathon-com-pix-como-configurar
- **Alerta de doação (novembro/2026):** leitura de toda doação em voz alta (opcional, sem custo extra, vozes neurais em português do Brasil: Vitória, Camila e Thiago; lê quem mandou, o valor e a mensagem inteira; mensagem barrada pelo filtro de conteúdo vira só "Fulano mandou X reais"); vozes de IA, inclusive de personagens, que quem doa escolhe a partir de R$ 5 (falam no lugar da leitura); áudio de até 20 s gravado por quem doa; estilos (Pílula, Pixel, Monograma, Pílula grande, Balão, Adesivo), temas claro e escuro e cor de destaque; temas com cores próprias na aba Temas (Neon, com estrelas que acendem conforme o valor, e Natal até 06/01/2027); variações de estilo, cor, som e duração por valor; aprovação antes de mostrar e fila controlável pelo Stream Deck.
- **App:** BotaPix para Android na Google Play (`com.botapix.app`), com saldo, doações e mapa IRL ao vivo no OBS; iPhone em breve.
## Versões em markdown pra assistentes e crawlers
- Toda página de `/docs` e `/blog` tem versão markdown crua: **acrescente `.md` à URL** (ex.: `https://botapix.com/docs/cobrancas/criar.md`).
- [llms-full.txt](https://botapix.com/llms-full.txt): este índice + o conteúdo integral das páginas, da documentação, do blog e das perguntas frequentes (home e Central de Ajuda), num arquivo só.
## Gateway de pagamentos (páginas do produto)
- [API de pagamentos Pix](https://botapix.com/api) ([markdown](https://botapix.com/api.md)): cobranças, assinaturas por Pix Automático, produtos com entrega automática, saldo, saques, devoluções e webhooks, com ambiente de testes.
- [Loja no Discord](https://botapix.com/discord) ([markdown](https://botapix.com/discord.md)): vitrine de produtos no servidor, botão Comprar, Pix numa mensagem que só o comprador vê e entrega automática por mensagem e DM.
- [Taxas](https://botapix.com/taxas) ([markdown](https://botapix.com/taxas.md)): todas as tarifas e um simulador de quanto fica com o vendedor.
- [Gateway de pagamento Pix: como funciona e como escolher](https://botapix.com/gateway-pix) ([markdown](https://botapix.com/gateway-pix.md)): o que é um gateway Pix, como o dinheiro anda, gateway x PSP, MED e os nove pontos para comparar.
- [Condições especiais](https://botapix.com/condicoes-especiais) ([markdown](https://botapix.com/condicoes-especiais.md)): proposta de tarifa para quem recebe a partir de R$ 50 mil por mês.
## Para streamers (páginas de doação e widgets)
- [Live de GTA 6 com Pix: maratona (subathon), voz e tema Neon](https://botapix.com/blog/live-de-gta-6-com-pix): Como montar a live de GTA 6 com Pix: maratona (subathon) que ganha tempo a cada doação, alerta que lê toda doação em voz alta e tema Neon.
- [Como colocar live pix na sua live: Twitch, Kick, YouTube e OBS](https://botapix.com/blog/como-receber-pix-na-live-guia-streamer): O que é live pix (doação via Pix com alerta na live), quanto custa e o passo a passo pra criar a página `/s/usuario`, ligar o alerta no OBS e divulgar na Twitch, na Kick e no YouTube.
- [Sub, bits e raid da Twitch e da Kick no mesmo alerta do Pix](https://botapix.com/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs): Como conectar as contas e o que aparece no widget.
- [Maratona (subathon) com Pix, subs e bits](https://botapix.com/blog/maratona-subathon-com-pix-como-configurar): Regras de tempo, teto, pausa e o widget do cronômetro.
- [Recompensas para quem doa ou assina](https://botapix.com/blog/recompensas-para-quem-doa-ou-assina): Link, código ou conteúdo secreto entregue na confirmação do Pix.
- [Enquetes com Pix na live](https://botapix.com/blog/enquetes-com-pix-na-live): A audiência vota com Pix e o resultado aparece no widget.
- [Stream Deck: pausar, pular e silenciar alertas](https://botapix.com/blog/stream-deck-pausar-pular-e-silenciar-alertas): Token de controle remoto e as URLs de cada tecla.
- [App BotaPix para Android e o mapa IRL ao vivo](https://botapix.com/blog/app-botapix-android-mapa-irl-ao-vivo): O que o app faz e como transmitir o trajeto no OBS.
- [5 erros que reduzem doações na sua live (e como corrigir)](https://botapix.com/blog/5-erros-que-reduzem-doacoes-na-live): Boas práticas de página de doação, alerta e call-to-action pra converter viewer em doador.
- [LivePix, Tipa.ai ou BotaPix? Comparativo de taxas de Pix em live (2026)](https://botapix.com/blog/botapix-vs-alternativas-comparativo-2026): Alternativas ao LivePix comparadas — taxa por doação e por saque de LivePix (5%), Tipa.ai (3,99%) e BotaPix (3%), e quanto sobra de cada R$ 1.000 doado.
- [Doação Pix na Twitch: Pix ou bits?](https://botapix.com/blog/doacao-pix-na-twitch-pix-ou-bits): Por que receber por Pix (~3%) em vez de bits/subs da Twitch (que retêm 30–50%, pagam em dólar e demoram no repasse), e como configurar o Pix na sua live da Twitch.
- [Pix que roda vídeo na live (media request)](https://botapix.com/blog/pix-que-roda-video-na-live-media-request): Como funciona o Media Share do BotaPix — o doador paga por segundo pra tocar um vídeo do YouTube na live, com preço por segundo, fila de moderação e banimento de vídeo, tudo configurado no OBS.
- **Widgets disponíveis** (Browser Source no OBS): Alerta de doação (estilos e temas, som, leitura de toda doação em voz alta, vozes de IA e áudio gravado pelo doador, sub/bits/raid da Twitch e da Kick), QR Code, Ranking de doadores, Meta, Histórico de doações, Enquete, Maratona (subathon) e Media Share (o doador paga por segundo pra tocar um vídeo do YouTube na live, com moderação do streamer).
## API — Introdução e primeiros passos
- [Introdução](https://botapix.com/docs): API REST para cobranças Pix, assinaturas via Pix Automático e notificações por webhook.
- [Primeiros passos](https://botapix.com/docs/primeiros-passos): Do zero ao webhook no ambiente de testes: credenciais de teste, cobrança, simulação do pagamento e confirmação, e a troca para produção.
- [Ambientes e testes](https://botapix.com/docs/ambientes-e-testes): Produção e ambiente de testes: chaves, cobranças, assinaturas, simulações e webhooks de teste, sem movimentar dinheiro.
- [Antes de ir para produção](https://botapix.com/docs/antes-de-producao): Lista de verificação para publicar a integração: credenciais, cobranças, webhooks, erros e conciliação.
- [Integrando com IA](https://botapix.com/docs/integrando-com-ia): Como usar assistentes de IA na integração: versões em Markdown, llms.txt, especificação OpenAPI e cuidados com credenciais.
- [Autenticação](https://botapix.com/docs/autenticacao): Autenticação por API key e limites de requisições.
- [Convenções](https://botapix.com/docs/convencoes): Formato de requisições e respostas, valores em centavos, datas em UTC, paginação, identificadores e ambiente.
- [Erros](https://botapix.com/docs/erros): Status HTTP, formato das respostas de erro e códigos retornados pela API.
- [Changelog](https://botapix.com/docs/changelog): Mudanças da API e dos webhooks, da mais recente para a mais antiga.
## API — Cobranças (Pix avulso)
- [Criar cobrança](https://botapix.com/docs/cobrancas/criar): Cria uma cobrança Pix de valor fixo e retorna a URL da página de pagamento.
- [Consultar cobrança](https://botapix.com/docs/cobrancas/consultar): Retorna uma cobrança pelo identificador numérico ou pelo reference.
- [Listar cobranças](https://botapix.com/docs/cobrancas/listar): Lista as cobranças da conta, da mais recente para a mais antiga, com filtros e paginação.
- [Estatísticas](https://botapix.com/docs/cobrancas/estatisticas): Retorna totais agregados e série temporal das cobranças criadas em um período.
- [Idempotência](https://botapix.com/docs/cobrancas/idempotencia): Repetição segura de requisições de criação com o header Idempotency-Key.
- [Exibir o QR no seu site](https://botapix.com/docs/cobrancas/exibir-qr): QR Code e Pix Copia e Cola na resposta da cobrança, para contas com a exibição liberada.
## API — Assinaturas (Pix Automático)
- [Criar assinatura](https://botapix.com/docs/assinaturas/criar): Cria uma assinatura mensal via Pix Automático e retorna o código de autorização para o pagador.
- [Consultar e listar](https://botapix.com/docs/assinaturas/consultar): Retorna uma assinatura pelo identificador ou lista as assinaturas da conta.
- [Cancelar assinatura](https://botapix.com/docs/assinaturas/cancelar): Cancela uma assinatura e encerra a autorização no banco do pagador.
## API — Dinheiro
- [Saldo e extrato](https://botapix.com/docs/dinheiro/saldo-e-extrato): Consulta o saldo da conta e lista os lançamentos que o formam.
- [Saques](https://botapix.com/docs/dinheiro/saques): Solicita saques do saldo disponível para a chave Pix cadastrada na conta e consulta os saques.
- [Devoluções](https://botapix.com/docs/dinheiro/devolucoes): Devolve ao pagador todo ou parte do valor de uma cobrança paga e consulta as devoluções.
- [Disputas (MED)](https://botapix.com/docs/dinheiro/disputas): Consulta as disputas abertas pelo banco do pagador por meio do MED e acompanha o valor bloqueado.
## API — Produtos (entrega automática)
- [Catálogo de produtos](https://botapix.com/docs/produtos/catalogo): Cria e mantém produtos com entrega automática por texto, link ou chave de licença, e abastece o estoque de chaves.
- [Vender um produto](https://botapix.com/docs/produtos/vender): Cria a cobrança de um produto do catálogo, com estoque reservado e entrega automática, e consulta o que o comprador recebeu.
## API — Webhooks (notificações)
- [Visão geral](https://botapix.com/docs/webhooks/visao-geral): Notificações HTTP enviadas ao seu servidor quando pagamentos e assinaturas mudam de status.
- [Configurar](https://botapix.com/docs/webhooks/configurar): Cadastro de endpoints, escolha de eventos, secret de assinatura e troca sem interrupção, evento de teste, log de entregas e implementação do endpoint.
- [Verificação HMAC](https://botapix.com/docs/webhooks/assinatura-hmac): Verificação do header X-BotaPix-Signature com HMAC-SHA256, com exemplos em PHP, Node.js e Python.
- [Eventos](https://botapix.com/docs/webhooks/eventos): Envelope comum dos eventos, lista dos eventos enviados e origem dos pagamentos.
- [Retentativas](https://botapix.com/docs/webhooks/retry-policy): Política de novas tentativas para entregas de webhook sem confirmação.
- [Testar localmente](https://botapix.com/docs/webhooks/testar-localmente): Receber eventos de webhook num servidor em execução na sua máquina, com Cloudflare Tunnel ou ngrok.
- [payment.confirmed](https://botapix.com/docs/eventos/payment-confirmed): Enviado quando um pagamento é confirmado e o valor líquido é creditado no saldo da conta.
- [payment.refunded](https://botapix.com/docs/eventos/payment-refunded): Enviado quando o valor integral de um pagamento é devolvido ao pagador, por devolução ou por MED.
- [payment.expired](https://botapix.com/docs/eventos/payment-expired): Enviado quando uma cobrança vence sem ser paga.
- [subscription.activated](https://botapix.com/docs/eventos/subscription-activated): Enviado quando o pagador autoriza uma assinatura.
- [subscription.rejected](https://botapix.com/docs/eventos/subscription-rejected): Enviado quando a autorização de uma assinatura é recusada.
- [subscription.canceled](https://botapix.com/docs/eventos/subscription-canceled): Enviado quando uma assinatura é cancelada pela API, pelo pagador ou pela instituição financeira.
- [withdrawal.scheduled](https://botapix.com/docs/eventos/withdrawal-scheduled): Enviado quando um saque ganha data de envio: logo após o pedido ou após a aprovação.
- [withdrawal.completed](https://botapix.com/docs/eventos/withdrawal-completed): Enviado quando o Pix do saque é enviado para a chave da conta.
- [withdrawal.failed](https://botapix.com/docs/eventos/withdrawal-failed): Enviado quando o saque não é realizado. O valor volta para o saldo disponível.
- [withdrawal.canceled](https://botapix.com/docs/eventos/withdrawal-canceled): Enviado quando o saque é cancelado antes do envio. O valor volta para o saldo disponível.
- [refund.completed](https://botapix.com/docs/eventos/refund-completed): Enviado quando a devolução é concluída e o valor chega ao pagador.
- [refund.failed](https://botapix.com/docs/eventos/refund-failed): Enviado quando a devolução não é realizada. O valor volta para o saldo disponível.
- [dispute.opened](https://botapix.com/docs/eventos/dispute-opened): Enviado quando o banco do pagador abre uma disputa (MED) sobre um pagamento. O valor contestado é bloqueado no saldo.
- [dispute.updated](https://botapix.com/docs/eventos/dispute-updated): Enviado quando a disputa passa para análise.
- [dispute.closed](https://botapix.com/docs/eventos/dispute-closed): Enviado quando a disputa é encerrada. O status indica o resultado.
- [delivery.completed](https://botapix.com/docs/eventos/delivery-completed): Enviado quando a venda de um produto é entregue ao comprador, depois da confirmação do Pix.
- [delivery.failed](https://botapix.com/docs/eventos/delivery-failed): Enviado quando a venda de um produto é paga e faltam chaves no estoque para a entrega completa.
- [webhook.test](https://botapix.com/docs/eventos/webhook-test): Evento de teste enviado pelo botão Enviar teste de um endpoint no dashboard.
## API — Streamers (controles do alerta)
- [Controles de alerta](https://botapix.com/docs/streamers/controle-de-alertas): Controle remoto do widget de alertas: pausa, repetição, fila e vozes.
## API — Referência
- [Especificação OpenAPI 3.1](https://botapix.com/docs/openapi.json): Especificação completa da API pública, dos controles de alerta e dos webhooks, em JSON.
- [Explorar API](https://botapix.com/docs/explorar): Referência interativa gerada a partir da especificação OpenAPI.
## Guias (blog)
Guias em português pra streamers e integradores. Cada post também existe em `.md` (acrescente `.md` à URL).
- [Live de GTA 6 com Pix: maratona (subathon), voz e tema Neon](https://botapix.com/blog/live-de-gta-6-com-pix): Passo a passo da live de GTA 6 com Pix: maratona (subathon) que ganha 1 minuto por real doado, alerta que lê toda doação em voz alta sem custo extra, tema Neon com estrelas pelo valor e enquete para o chat escolher a missão.
- [Sub, bits e raid da Twitch e da Kick no mesmo alerta do Pix](https://botapix.com/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs): Conecte sua conta da Twitch ou da Kick ao BotaPix e cada sub, bits, raid, follow ou Kick vira alerta no mesmo widget das doações, com toggles por tipo e mínimo de bits.
- [Stream Deck: pausar, pular e silenciar os alertas com uma tecla](https://botapix.com/blog/stream-deck-pausar-pular-e-silenciar-alertas): Gere um token de controle remoto e ligue cada tecla do Stream Deck a uma ação do widget de alerta: pausar, retomar, pular o alerta atual, silenciar a voz e disparar um teste. O token não acessa saldo nem saques.
- [Recompensas: link, código ou conteúdo secreto para quem doa ou assina](https://botapix.com/blog/recompensas-para-quem-doa-ou-assina): Cadastre uma recompensa, defina o valor mínimo ou o gatilho de assinatura, e o apoiador recebe o link ou o conteúdo na tela de confirmação do Pix. Revogação automática se a assinatura cair.
- [Maratona (subathon) com Pix, subs e bits: como configurar](https://botapix.com/blog/maratona-subathon-com-pix-como-configurar): Um cronômetro que ganha tempo com cada doação em Pix, sub, bits, Kicks ou raid. Regras por evento, teto de horas, pausa, ajuste manual e widget pronto pro OBS.
- [Enquetes com Pix: a audiência decide, e paga por isso](https://botapix.com/blog/enquetes-com-pix-na-live): Crie uma enquete com até seis opções, escolha se cada real vale um voto ou cada doação vale um voto, e mostre o resultado ao vivo no widget. O voto conta quando o Pix é pago.
- [App BotaPix para Android: receba Pix na live e acompanhe tudo pelo celular](https://botapix.com/blog/app-botapix-android-mapa-irl-ao-vivo): O app do BotaPix está na Google Play. Saldo, saque, histórico de doações e o mapa IRL ao vivo no OBS, tudo pelo celular. O app de doação para streamer que fecha o ciclo do Pix na live. iPhone em breve.
- [Pix que roda vídeo na live: como funciona o media request (e como configurar)](https://botapix.com/blog/pix-que-roda-video-na-live-media-request): Deixe quem doa escolher um vídeo do YouTube pra tocar na sua live. Como funciona o media request no BotaPix: preço por segundo, fila de moderação, banimento de vídeo e configuração no OBS.
- [Doação Pix na Twitch: por que streamers preferem Pix aos bits (e como configurar)](https://botapix.com/blog/doacao-pix-na-twitch-pix-ou-bits): Bits e subs deixam 30–50% com a Twitch, pagam em dólar e demoram semanas. Doação via Pix chega em segundos com taxa de ~3%. A matemática lado a lado e o passo a passo pra configurar.
- [Assinaturas via Pix Automático: como cobrar todo mês sem o cliente fazer nada](https://botapix.com/blog/assinaturas-pix-automatico-no-botapix): Pix Automático chegou e muda a cobrança recorrente no Brasil: o cliente autoriza uma vez no app do banco e o valor é debitado todo mês, sem cartão e sem ele precisar pagar de novo. Veja como funciona e como ativar no BotaPix — pela dashboard ou via API.
- [Como receber Pix na live: passo a passo pro streamer iniciante (2026)](https://botapix.com/blog/como-receber-pix-na-live-guia-streamer): Passo a passo completo pra receber doações Pix na live: escolher a plataforma, configurar o alerta no OBS e testar antes de ir ao ar — tudo em texto, sem precisar assistir 40 minutos de vídeo.
- [LivePix, Tipa.ai ou BotaPix? Comparativo de taxas de Pix em live (2026)](https://botapix.com/blog/botapix-vs-alternativas-comparativo-2026): Procurando uma alternativa ao LivePix? Comparamos taxa por doação, taxa de saque e recursos de LivePix, Tipa.ai e BotaPix — e quanto de cada R$ 1.000 doado chega de fato na sua conta.
- [MED do Pix: o que é, como funciona e o que acontece com seu saldo se um cliente abrir uma disputa](https://botapix.com/blog/med-do-pix-o-que-e-e-como-protege-vendedor): Mecanismo Especial de Devolução do Pix (MED) explicado pra quem recebe: como funciona, qual o prazo, o que o BACEN avalia e como gateways como o BotaPix protegem seu saldo durante a análise.
- [5 erros que reduzem doações na sua live (e como corrigir)](https://botapix.com/blog/5-erros-que-reduzem-doacoes-na-live): Cinco problemas técnicos e de UX que estão custando doações sem você notar — QR Code ilegível, posicionamento do alerta, TTS robotizado, link escondido e ausência de meta visual.
---
# Conteúdo completo
O que segue é o corpo integral da documentação e dos guias do BotaPix, em markdown. Cada bloco indica a URL-fonte.
---
# Sem título
Fonte: https://botapix.com/api
# API de pagamentos Pix do BotaPix
Fonte: https://botapix.com/api · Documentação: https://botapix.com/docs
O BotaPix é um gateway de pagamentos Pix com API REST para sites, apps, jogos e sistemas. Uma chamada cria a cobrança; o pagador paga no checkout pronto do BotaPix ou, com o checkout transparente ativo, no QR que você exibe na sua própria tela; o seu servidor recebe o webhook `payment.confirmed` assinado com HMAC-SHA256.
## O que a API faz
- **Cobranças Pix** (`POST /api/v1/charges`): valor em centavos, prazo de 5 minutos a 24 horas, referência externa, metadata livre e `Idempotency-Key`.
- **Assinaturas por Pix Automático** (`POST /api/v1/subscriptions`): o pagador autoriza uma vez no banco e o débito acontece todo mês.
- **Produtos com entrega automática** (`/api/v1/products`): texto, link ou chave de licença entregue na confirmação do Pix, com estoque reservado durante a cobrança.
- **Dinheiro**: saldo, extrato, saques para a chave Pix do titular, devoluções totais ou parciais e disputas (MED).
- **Webhooks**: vários endpoints por conta, escolha de eventos, assinatura HMAC-SHA256, até 8 tentativas ao longo de cerca de 33 horas e log de entregas no dashboard.
- **Ambiente de testes**: chaves `btpx_test_` com cobranças, assinaturas e simulação de pagamento, expiração e devolução, sem dinheiro real.
## Números
- 600 criações de cobrança por minuto e 200 consultas por minuto, por chave de API.
- 3% por pagamento confirmado. Sem mensalidade, adesão ou faturamento mínimo.
- Saque: 1,5% (mínimo R$ 0,50), saque mínimo de R$ 10,00, sempre para a chave Pix do titular da conta.
## Exemplo
```bash
curl https://botapix.com/api/v1/charges \
-H "Authorization: Bearer $BOTAPIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "amount": 4990, "external_reference": "pedido_1042" }'
```
A resposta traz `payment_url`, a página de pagamento hospedada. Quando o Pix é pago, chega o evento `payment.confirmed` com o mesmo `external_reference`.
## Perguntas frequentes
### Preciso de contrato ou mensalidade para usar a API?
Não. A conta é gratuita e a API vem junto: você gera a chave em Dashboard → API & Webhooks. A taxa é de 3% por pagamento confirmado, sem mensalidade, adesão ou valor mínimo de faturamento.
### Consigo testar sem movimentar dinheiro?
Sim. Chaves de teste (prefixo btpx_test_) criam cobranças e assinaturas de teste, e você simula pagamento, expiração e devolução pela própria API ou pelo dashboard. Os eventos chegam no seu webhook de teste com livemode: false.
### O pagador precisa sair do meu site para pagar?
Não precisa. Toda cobrança já vem com um checkout pronto (payment_url), com QR, Pix copia e cola e confirmação em tempo real, que você abre em nova aba, num pop-up ou por redirecionamento. Se preferir o pagamento dentro da sua própria tela, ative o checkout transparente no dashboard: a API passa a devolver o QR e o copia e cola para você exibir no site, app ou jogo.
### Como fico sabendo que o Pix foi pago?
Pelo webhook payment.confirmed, assinado com HMAC-SHA256. Se o seu servidor não responder 2xx, o BotaPix faz até 8 tentativas ao longo de cerca de 33 horas, sempre com o mesmo event_id para você descartar repetidos. A cobrança também pode ser consultada a qualquer momento.
### Quais são os limites de requisição?
600 criações de cobrança por minuto e 200 consultas por minuto, por chave de API (não por IP). Para escalar, use mais de uma chave: cada uma tem o próprio limite.
### Dá para sacar e devolver pagamentos pela API?
Sim, com uma chave Financeiro: saldo, extrato, saques para a chave Pix cadastrada na conta e devoluções totais ou parciais. O saque vai sempre para a chave do titular da conta; a API não aceita chave Pix de destino.
---
# Sem título
Fonte: https://botapix.com/discord
# Loja no Discord com Pix e entrega automática
Fonte: https://botapix.com/discord
A Loja no Discord do BotaPix publica os seus produtos como cards num canal do servidor. Cada card tem o botão **Comprar**.
## Como funciona
1. **Vitrine.** Você conecta o servidor ao BotaPix, escolhe o canal e os produtos (até 25) e publica. Cada card mostra nome, descrição, preço, estoque e o botão Comprar.
2. **Pedido.** Quem clica em Comprar recebe uma mensagem que só ele vê, com o QR do Pix, o código copia e cola e o prazo de 10 minutos.
3. **Entrega.** Quando o Pix é confirmado, a mesma mensagem passa a mostrar o que foi comprado: um texto, um link ou uma chave de licença do estoque. A entrega também vai por mensagem direta e fica numa página do comprador.
4. **Log.** O bot pode avisar cada venda num canal da equipe, com ou sem o valor.
## Detalhes
- Sem bot próprio para hospedar: o bot é do BotaPix.
- Estoque por quantidade ou por chaves; o card mostra o que resta e desliga o botão quando esgota.
- Um pedido em aberto reserva a unidade só para aquela pessoa até o Pix vencer; clicar de novo reaproveita o mesmo pedido.
- Taxa: 3% por pagamento confirmado, a mesma de qualquer venda no BotaPix.
- Os produtos são os mesmos do dashboard e da API (`/api/v1/products`), e as vendas aparecem em Pagamentos com a origem `discord`.
## Perguntas frequentes
### Preciso hospedar um bot?
Não. Você conecta o servidor ao BotaPix em um clique e escolhe o canal da vitrine. O bot é nosso e roda na nossa infraestrutura.
### O que o comprador vê ao clicar em Comprar?
Uma mensagem que só ele enxerga, com o QR do Pix, o código copia e cola e o prazo para pagar. O canal não fica cheio de pedidos e ninguém vê o que o outro comprou.
### Como funciona a entrega?
Assim que o Pix é confirmado, a mesma mensagem passa a mostrar o que foi comprado: um texto, um link ou uma chave de licença do seu estoque. A entrega também vai por mensagem direta e fica numa página própria do comprador.
### E se acabar o estoque?
O card mostra quantas unidades restam e o botão Comprar se desliga quando esgota. Enquanto um pedido não é pago, a unidade fica reservada só para aquela pessoa, até o Pix vencer.
### Quanto custa?
A mesma taxa de qualquer venda no BotaPix: 3% por pagamento confirmado. A loja, o bot e o canal de log de vendas não têm custo extra.
---
# Sem título
Fonte: https://botapix.com/condicoes-especiais
# Condições especiais para alto volume
Fonte: https://botapix.com/condicoes-especiais
Negócios que recebem muito por Pix, em geral a partir de R$ 50 mil por mês, podem pedir uma proposta de tarifa ao BotaPix. O formulário pede nome, e-mail, empresa, site, volume mensal, tipo de negócio e uma mensagem opcional. A resposta vem por e-mail.
Podem ser ajustados, caso a caso: a tarifa por pagamento, a tarifa e os limites de saque e o prazo de liberação dos saques. A tarifa padrão continua valendo para todos: 3% por Pix confirmado, sem mensalidade (https://botapix.com/taxas).
## Perguntas frequentes
### Quem pode pedir condição especial?
Negócios que recebem um volume alto por Pix, em geral a partir de R$ 50 mil por mês. Abaixo disso, a tarifa padrão de 3% sem mensalidade costuma ser a melhor opção.
### O que pode mudar na condição especial?
Tarifa por pagamento, tarifa e limites de saque e o prazo de liberação dos saques, conforme o volume, o histórico e o risco do negócio. Cada proposta é feita caso a caso.
### Preciso ter conta para pedir?
Não. Responda o formulário e a proposta chega por e-mail. Se ainda não tiver conta, você cria depois e a condição é aplicada nela.
### Em quanto tempo recebo resposta?
Respondemos por e-mail, em geral em até dois dias úteis.
---
# Sem título
Fonte: https://botapix.com/gateway-pix
# Gateway de pagamento Pix: como funciona e como escolher
Fonte: https://botapix.com/gateway-pix
Um gateway de pagamento Pix é o serviço que cria cobranças Pix em nome de quem vende, recebe o pagamento numa instituição de pagamento autorizada pelo Banco Central, avisa o sistema do vendedor quando o dinheiro cai e repassa o saldo por saque.
## Como o dinheiro anda
1. **Cobrança.** O sistema do vendedor (ou um link de pagamento) pede ao gateway uma cobrança com valor e prazo. O gateway devolve o QR e o código Pix copia e cola, ou uma página de pagamento pronta.
2. **Pagamento.** O cliente paga pelo app do banco. O dinheiro entra na conta do gateway no PSP.
3. **Confirmação.** O gateway confirma o pagamento e envia um webhook assinado para o servidor do vendedor, que libera o pedido.
4. **Saldo.** O valor, já descontada a tarifa, fica no saldo do vendedor dentro do gateway.
5. **Saque.** O vendedor transfere o saldo para a própria chave Pix.
## O que comparar antes de escolher
- **Tarifa por Pix recebido** e se existe parte fixa por pagamento.
- **Saque:** tarifa, valor mínimo, prazo e se o destino precisa ser do titular.
- **Mensalidade, adesão ou faturamento mínimo.**
- **Webhooks:** assinatura (HMAC), número de retentativas, vários endpoints e log de entregas.
- **Ambiente de testes** para validar o fluxo sem dinheiro real.
- **Devoluções** pela API e prazo para devolver.
- **MED:** como o gateway mostra e bloqueia valores em disputa.
- **Checkout:** página pronta e, se precisar, checkout transparente (o QR na sua própria tela).
- **Limites de requisição** da API.
## Gateway, PSP e banco
O PSP é a instituição autorizada que movimenta o Pix. O gateway fica entre o PSP e o vendedor: cobra, confirma, mantém o saldo de cada vendedor e faz o repasse. Quem vende integra só com o gateway.
## BotaPix
- 3% por Pix confirmado, sem mensalidade nem adesão.
- Saque de 1,5% (mínimo R$ 0,50) para a chave Pix do titular.
- Webhooks HMAC-SHA256 com até 8 tentativas ao longo de cerca de 33 horas, vários endpoints e log de entregas.
- Ambiente de testes com chaves `btpx_test_`.
- Devoluções totais ou parciais pela API e disputas (MED) consultáveis.
- Documentação: https://botapix.com/docs · API: https://botapix.com/api
## Perguntas frequentes
### O que é um gateway de pagamento Pix?
É o serviço que gera a cobrança Pix em nome do vendedor, recebe o pagamento numa instituição de pagamento autorizada pelo Banco Central, avisa o sistema do vendedor quando o Pix cai e repassa o dinheiro por saque. O pagador vê só o QR e o valor, não a chave Pix pessoal de quem vende.
### Qual a diferença entre gateway, PSP e banco?
O PSP (prestador de serviço de pagamento) é a instituição autorizada que movimenta o Pix. O gateway fica entre o PSP e o vendedor: cria as cobranças, confirma pagamentos por webhook, mantém o saldo de cada vendedor e faz o repasse. O vendedor integra com o gateway e não precisa de contrato com o PSP.
### Quanto custa um gateway Pix?
Varia entre os serviços. Compare a tarifa por Pix recebido, a tarifa e o mínimo de saque, a existência de mensalidade e o custo de assinatura recorrente. No BotaPix, são 3% por Pix confirmado, saque de 1,5% (mínimo R$ 0,50) e nenhuma mensalidade.
### O que é MED e como afeta o vendedor?
O MED (Mecanismo Especial de Devolução) permite que o banco do pagador conteste um Pix em casos de suspeita de fraude. Enquanto a disputa está aberta, o valor contestado fica bloqueado no saldo do vendedor; se a disputa for aceita, o valor volta ao pagador.
### Como integrar um gateway Pix no meu site?
Pela API: o seu servidor cria a cobrança, o cliente paga no checkout do gateway (ou no QR exibido na sua tela, com checkout transparente) e o seu servidor recebe um webhook quando o Pix é confirmado. Antes de ir para produção, teste o fluxo inteiro com chaves de teste.
---
# Sem título
Fonte: https://botapix.com/taxas
# Taxas do BotaPix
Fonte: https://botapix.com/taxas
| Operação | Tarifa |
|---|---|
| Pagamento avulso (doação, link, produto, API, Discord) | 3% do valor pago |
| Assinatura (Pix Automático) | R$ 3,50 + 3% por cobrança mensal; assinatura mínima de R$ 10,00 |
| Saque | 1,5% do valor sacado, mínimo de R$ 0,50; saque mínimo de R$ 10,00 |
| Cobrança que vence sem pagamento | Grátis |
| Mensalidade, adesão, inatividade | Não existem |
| Devolução ao pagador | O valor pago sai do saldo; a tarifa do pagamento não volta |
## Exemplo
Uma venda de R$ 100,00 deixa R$ 97,00 no saldo. Sacar esses R$ 97,00 custa R$ 1,46 (1,5%), e chegam R$ 95,54 na sua chave Pix.
## Perguntas frequentes
### Existe mensalidade ou taxa de adesão?
Não. Você paga só quando recebe: 3% de cada pagamento confirmado. Cobrança que vence sem pagamento não custa nada.
### Quanto custa uma assinatura?
R$ 3,50 + 3% a cada débito do Pix Automático, descontados do valor recebido. O valor mínimo de uma assinatura é R$ 10,00.
### Quanto custa sacar?
1,5% do valor sacado, com mínimo de R$ 0,50 por saque, descontado do valor enviado. O saque mínimo é R$ 10,00 e vai para a chave Pix do titular da conta.
### Se eu devolver um pagamento, recebo a taxa de volta?
Não. A devolução manda de volta ao pagador o valor que ele pagou, e esse valor sai do seu saldo disponível. A taxa do pagamento original não é devolvida.
### Recebe um volume alto?
Peça uma condição especial em botapix.com/condicoes-especiais, com o volume mensal e o tipo de negócio. As propostas são avaliadas caso a caso.
---
# Perguntas frequentes
Fonte: https://botapix.com
## Taxas e saques
### Quais são as taxas cobradas?
Doações e pagamentos avulsos: 3% por transação confirmada. Assinaturas com Pix Automático: R$ 3,50 + 3% por cobrança. Sem mensalidade, sem anuidade e sem taxa de adesão. No saque, a tarifa é de 1,5% (mínimo R$ 0,50).
### Como funciona o saque?
O valor entra no seu saldo assim que o pagamento é confirmado. Você pode pedir saque a qualquer hora, para uma chave Pix no seu CPF. Cada saque passa por uma verificação de segurança e é processado em poucas horas. É o que protege você contra contestações indevidas. A tarifa de saque é de 1,5% (mínimo R$ 0,50), deduzida do valor transferido. Valor mínimo de R$ 10,00. Saques até R$ 500 são liberados automaticamente, sem aprovação manual.
### Quanto tempo leva para cair na minha conta?
O pagamento é confirmado em segundos via webhook e creditado no seu saldo, ficando disponível para saque logo após a confirmação. Em situações específicas de segurança ou disputa, um valor pode ficar temporariamente retido, conforme os Termos de Uso.
## Para streamers
### Como receber Pix durante a live?
O BotaPix foi feito para Pix na live: você compartilha sua página /s/seunome com o público da stream, e cada doação dispara um alerta no OBS em tempo real, com leitura por voz, ranking de doadores e barra de meta. O Pix entra na sua conta na hora, sem expor sua chave pessoal para o chat.
### O que é live pix?
É como muita gente chama a doação via Pix durante a live com alerta na tela: o espectador paga um Pix, o valor e a mensagem aparecem na transmissão e o streamer agradece na hora. O BotaPix faz isso na Twitch, na Kick e no YouTube, com 3% por doação e sem mensalidade.
### Funciona para streamers e criadores de conteúdo?
Sim. Criadores ganham uma página pública de doação personalizável em botapix.com/s/seunome, widgets para OBS (alertas, metas, ranking, QR Code), TTS com IA e integração com Streamlabs e StreamElements.
### É só para streamers de jogos?
Não. Funciona com lives de qualquer plataforma (Twitch, YouTube, Kick, TikTok, Instagram) e diversos formatos: música ao vivo, podcast, casts esportivos, IRL, just chatting. Onde houver uma transmissão ao vivo recebendo apoio do público, o BotaPix se encaixa, respeitados os Termos de Uso da plataforma.
### Posso receber apoio mensal recorrente?
Sim. Além de pagamentos avulsos, criadores podem oferecer apoio mensal via Pix Automático: o apoiador autoriza uma vez no banco e o valor é debitado automaticamente todo mês. Ele pode cancelar quando quiser pelo próprio banco.
### Tem aplicativo?
Sim. O app BotaPix para Android está na Google Play: acompanhe doações e saldo pelo celular e transmita seu trajeto ao vivo no OBS com o mapa IRL. A versão para iPhone está em desenvolvimento.
## Conta e segurança
### O BotaPix é seguro?
Operamos sobre a infraestrutura oficial do Pix, processada por instituição de pagamento autorizada pelo Banco Central do Brasil, e adotamos medidas de segurança adequadas para proteger suas informações. Sua chave Pix pessoal não fica exposta ao público.
### Preciso ter CNPJ?
Não. Pessoas físicas, com CPF, podem usar normalmente: crie sua conta e cadastre uma chave Pix no seu nome.
### Preciso verificar minha identidade?
No cadastro, validamos que o nome informado corresponde ao titular do CPF e que o titular tem 18 anos ou mais. Em situações específicas de segurança, podemos solicitar uma verificação adicional (documento com foto e selfie) antes de liberar saques. É uma medida de proteção contra fraude.
## Para desenvolvedores
### Como integro no meu site?
Gere sua API Key no painel e faça um POST para /api/v1/charges com o valor. A resposta traz o payment_url: redirecione o cliente para essa página, que mostra o QR Code e o Pix Copia e Cola. Webhooks assinados avisam o seu sistema quando o pagamento é confirmado.
---
# Central de Ajuda do BotaPix (no painel, para quem tem conta)
Fonte: https://botapix.com/dashboard/ajuda
## Começando
### O Pix foi pago e não apareceu?
A confirmação vem do banco e normalmente aparece em segundos: a página de pagamento atualiza sozinha. Em raros momentos o banco pode levar mais tempo para avisar. Se passou de alguns minutos e não confirmou, peça ao pagador o comprovante e abra um chamado com ele: a equipe localiza a transação.
### O que é o BotaPix e como funciona?
O BotaPix é uma plataforma para receber pagamentos via Pix sem expor sua chave pessoal. Você gera uma cobrança (pela sua página, por uma vaquinha ou pela API), o cliente paga via Pix, e o valor cai no seu saldo na hora — já descontada a taxa. Depois você saca para a sua chave Pix.
### Como uso o QR Code de pagamento?
Toda cobrança gera um QR Code e um código Pix Copia e Cola na página de pagamento. O pagador pode escanear o QR com a câmera do app do banco, ou copiar o código e colar na opção "Pix Copia e Cola". Os dois levam ao mesmo pagamento.
### Como exporto meus pagamentos?
Em Pagamentos, use o botão "Exportar" para baixar um CSV das suas transações, respeitando os filtros que estiverem aplicados (status, período, busca). Serve para conferência e contabilidade.
## Programa de Afiliados
### Como funciona o programa de afiliados?
Você compartilha seu link de indicação (em Afiliados, no menu). Cada pessoa que criar conta por ele fica vinculada a você, e todo mês você recebe uma porcentagem do lucro que o BotaPix tiver com esses usuários. A apuração acontece todo dia 3, e o valor fica disponível para transferência 30 dias depois. O programa é exclusivo para contas de pessoa física (CPF).
### O programa de afiliados pode mudar ou acabar?
Pode. O programa é um benefício de divulgação: o BotaPix pode ajustar o percentual e as regras, ou encerrá-lo, sempre com aviso prévio. O que já foi apurado é seu e será pago normalmente: mudanças nunca atingem comissão já creditada. As condições completas estão nos Termos de Uso.
### Por que preciso de verificação de identidade para ser afiliado?
O programa paga em dinheiro. Para proteger a plataforma contra fraude, o link de indicação só é liberado para contas com nome de usuário público (o @ da sua página) e identidade verificada. A verificação é feita na página Verificação (documento com foto e selfie) e também garante o selo "Verificado" na sua página pública.
### Como recebo minhas comissões?
A comissão apurada entra primeiro como "em liberação" e, após o período de carência, fica disponível. Aí é só transferir para o seu saldo (com confirmação de senha) e sacar pelo fluxo normal de saques, para a sua própria chave Pix.
### A comissão é sobre o quanto meus indicados movimentam?
Não. A base é o lucro líquido do BotaPix com cada indicado. Meses sem lucro não geram comissão.
## Taxas e saques
### Quanto tempo demora meu saque?
Cada saque aguarda uma janela de segurança antes do Pix sair: é o tempo para uma eventual contestação de Pix aparecer antes de o dinheiro deixar a conta. O prazo diminui sozinho conforme a conta amadurece: até 72 horas para contas com até 7 dias, até 24 horas até 30 dias e até 3 horas depois disso. Saques acima de R$ 500,00 passam antes por análise da equipe, e o prazo conta a partir da aprovação. O prazo exato da sua conta aparece na tela de saque, antes de confirmar.
### Quais são as taxas?
Venda ou doação avulsa: 3% do valor recebido. Assinatura: R$ 3,50 + 3% por cobrança. Saque: 1,5% do valor, com mínimo de R$ 0,50, descontado do valor enviado. Recebeu R$ 100,00? Entram R$ 97,00 no saldo. Sem anuidade, sem taxa de adesão e sem mensalidade.
### Qual o valor mínimo e os limites de saque?
O valor mínimo de saque é R$ 10,00. Saques até R$ 500,00 são liberados automaticamente; acima disso, ou em situações de segurança, o saque pode passar por uma análise antes de ser processado.
### Meu saque foi cancelado e o valor voltou para o saldo. Por quê?
Se uma contestação (devolução via Pix) consumir parte do saldo enquanto o saque aguarda a janela de segurança, o saque é cancelado e o valor volta para o seu saldo — assim você saca o que restou, em vez de o Pix falhar no meio do caminho. Basta pedir o saque de novo.
### Para qual chave Pix posso sacar?
Por segurança, o saque só sai para uma chave Pix que pertença ao seu CPF — a titularidade é validada pelo banco no momento do envio. Chave de terceiros não passa. Você cadastra e troca sua chave em Configurações.
## Assinaturas (apoio recorrente)
### Como funcionam as assinaturas?
As assinaturas usam o Pix Automático do Banco Central: o apoiador autoriza uma única vez no app do banco dele e o débito acontece sozinho, sem precisar pagar de novo. Além do mensal, você pode oferecer planos trimestral, semestral e anual com o desconto que escolher (em Assinaturas no painel): o apoiador paga os meses de uma vez. O valor mínimo é R$ 10,00 por mês, e a tarifa é de R$ 3,50 + 3% por débito, então num plano longo o valor fixo sai uma vez só.
### Como cancelo uma assinatura?
Dos dois lados: você cancela qualquer assinatura sua na página Assinaturas do painel (o mandato é encerrado no banco do apoiador, que não é mais cobrado); e o apoiador também pode cancelar a qualquer momento pelo app do banco dele. Nos dois casos você é notificado e o status atualiza sozinho.
### O apoiador autorizou mas a assinatura não ativou. E agora?
A autorização depende do banco do apoiador e pode levar alguns instantes para ser confirmada. Enquanto isso a assinatura fica como "aguardando autorização". Se o apoiador recusou ou a autorização expirou, ela aparece como recusada — ele pode tentar assinar de novo.
## Minha página e widgets
### Como coloco os alertas de doação na minha live?
Em Minha Página → Widgets da live, abra o widget (alerta, QR Code, ranking, meta…) e clique em Adicionar ao OBS: ali está o link do widget, o tamanho certo e o passo a passo. No OBS ou Streamlabs, o link entra como fonte "Navegador" (Browser Source). As doações confirmadas disparam o alerta em tempo real.
### Como troco o nome que aparece na minha página?
Em Minha Página → Página de doação, no campo Nome exibido. A mudança salva sozinha e já aparece na página. Em branco, a página mostra o seu @. Por privacidade, o nome do seu cadastro (o do CPF) nunca aparece: se você digitar ele, a página continua mostrando o @. Use um apelido ou o nome do canal. Foto, imagem de fundo, bio e cor ficam no mesmo lugar.
### O alerta pode ler toda doação em voz alta?
Pode. Em Minha Página → Widgets da live → Alerta → Voz, ligue Ler as doações em voz alta: toda doação é lida, com quem mandou, o valor e a mensagem inteira, mesmo quando o alerta encurta o texto na tela. São três vozes em português do Brasil (Vitória, Camila e Thiago), com um exemplo para ouvir antes de escolher. A leitura não tem custo extra e vem desligada: liga quem quiser. A voz de IA que quem doa escolhe continua valendo e, nessa doação, fala no lugar da leitura.
### Como mudo o visual do alerta?
No editor do alerta, abaixo da prévia, escolha um estilo: Pílula, Pixel, Monograma, Pílula grande, Balão ou Adesivo, nos temas claro ou escuro, com a cor de destaque que quiser. Na aba Temas ficam os visuais com cores próprias, como o Neon (anos 80, com estrelas que acendem conforme o valor) e o Natal, que fica até 06/01 e depois volta sozinho para o estilo que você usava. Com variações por valor, uma doação maior pode aparecer com outro estilo.
### Por que a mensagem não foi narrada (TTS) no alerta?
Confira em Minha Página → Widgets da live → Alerta → Voz. Com Ler as doações em voz alta ligado, toda doação é lida. Com ele desligado, só fala a doação em que quem doa escolheu uma voz de IA, a partir do valor mínimo (padrão R$ 5,00) e com mensagem. Mensagem barrada pelo filtro de conteúdo não é lida: com a leitura ligada, a voz diz só quem mandou e o valor. Confira também se o alerta não está no mudo pelo Stream Deck ou pelo Ao vivo.
### Como funciona o áudio gravado pelo doador?
Se você ativar essa opção no widget, doações a partir de R$ 5,00 podem incluir um áudio gravado de até 20 segundos, que toca no alerta da live. Você controla a ativação e pode desligar quando quiser.
### Consigo controlar os alertas pelo Stream Deck?
Sim. Em Integrações → Stream Deck e controle remoto, gere um token e use um plugin de requisição HTTP do Stream Deck (ou qualquer atalho que faça POST) nas URLs listadas ali: pausar e retomar alertas, pular o alerta atual, silenciar a voz e disparar um alerta de teste. O token só controla o widget: não acessa saldo, saques nem cobranças.
### Subs, bits e raids da Twitch aparecem nos alertas?
Sim. Em Integrações → Twitch, clique em Conectar e autorize. Subs (novos, renovações e presentes), bits, raids e follows chegam pelo EventSub da Twitch e viram alerta no widget, com toggles e mínimo de bits na aba Alertas. Só alertas: nada de dinheiro passa por aqui.
### E a Kick?
Também. Em Integrações → Kick, conecte e autorize. Subs (novos, renovações e presentes), Kicks e follows chegam pelos webhooks da Kick e viram alerta, com toggles e mínimo de Kicks na aba Alertas. Kicks também somam tempo na Maratona.
### Como funciona a maratona (subathon)?
Em Minha Página → Widgets da live → Maratona você define quanto tempo cada coisa soma (padrão: 1 minuto por R$ 1 em Pix, 5 minutos por sub, 1 minuto por 100 bits ou 100 Kicks) e adiciona o cronômetro ao OBS. Na hora da live, inicie em Ao vivo → Maratona, com o tempo inicial e, se quiser, um teto de horas. Cada Pix pago soma tempo na hora, e vaquinha e assinatura também contam. Dá para pausar e ajustar minutos na mão. Quando o cronômetro zera, a maratona acaba e uma doação depois disso não traz o relógio de volta. O cronômetro tem cinco estilos (Relógio, Pílula, Notificação, Anel e Faixa), e o Fundo deixa o card translúcido sobre o jogo.
## Vaquinhas
### O que são vaquinhas e como crio uma?
Vaquinhas são páginas de arrecadação com meta e barra de progresso, com link próprio para divulgar. Qualquer conta pode criar em Vaquinhas → Nova vaquinha; não precisa ser streamer. Os valores arrecadados caem no mesmo saldo.
## API e integrações
### Onde gero minha chave de API?
Em API & Webhooks no painel. Lá você gera a chave (formato btpx_...), configura a URL de webhook do seu site e encontra o link da documentação completa em botapix.com/docs.
### Como meu site sabe que o pagamento foi confirmado?
Configurando um webhook em API & Webhooks: a cada pagamento confirmado, enviamos um POST assinado (HMAC) para a sua URL com os dados da cobrança. Também dá para consultar o status de uma cobrança a qualquer momento pela API. Os detalhes e exemplos estão na documentação.
## Cadastro e verificação
### Por que meu CPF aparece como inválido?
No cadastro, o nome informado precisa corresponder ao titular do CPF na base da Receita Federal, e o titular precisa ter 18 anos ou mais. Se o nome não bater com o do CPF, se o CPF não for encontrado, ou se o titular for menor de idade, o cadastro não é concluído. Confira se digitou seu nome completo exatamente como consta no seu documento.
### Por que pedem verificação de identidade (documento e selfie)?
Em algumas situações de segurança — por exemplo, um índice elevado de contestações na conta — podemos solicitar uma verificação de identidade antes de liberar saques: o envio de um documento com foto (frente e verso) e uma selfie. É uma medida de proteção contra fraude e uso indevido. Enquanto a verificação está pendente, recebimentos e saques ficam pausados; seu saldo continua seguro.
### O que torna uma conta irregular?
O cadastro exige que o nome corresponda ao titular do CPF (Receita Federal) e que o titular tenha 18 anos ou mais. Contas com indícios de risco — como alto índice de contestações — podem passar por verificação adicional de identidade. O uso da plataforma está sujeito aos Termos de Uso.
### Posso mudar meu nome ou excluir minha conta?
O nome da conta segue o titular do CPF e não é editável. A exclusão da conta é feita em Configurações; registros de transações são mantidos pelo período exigido por lei, conforme a Política de Privacidade.
## Contestações (MED)
### O que é o MED?
O MED (Mecanismo Especial de Devolução) é um recurso do Banco Central pelo qual o pagador pode contestar um Pix e solicitar a devolução do valor. Quando isso acontece, o valor correspondente fica temporariamente bloqueado no seu saldo enquanto a contestação é analisada, conforme as regras do Pix.
### Como o BotaPix lida com uma contestação?
O BotaPix é a provedora de tecnologia que viabiliza a cobrança via Pix; não participamos da relação entre você e o pagador. Diante de uma contestação, registramos os dados da transação disponíveis na plataforma e damos andamento conforme o fluxo do Banco Central. O bloqueio do valor é preventivo e segue as regras do Pix.
## Segurança e atendimento
### O BotaPix entra em contato pedindo senha ou código?
Nunca. O BotaPix não pede senha, código de verificação ou Pix por WhatsApp, Discord, ligação ou e-mail. Todo atendimento oficial acontece pelo Suporte aqui no painel ou pelo e-mail contato@botapix.com. Se alguém falar em nome do BotaPix pedindo dados ou pagamento, é golpe — não responda e nos avise pelo Suporte.
### Quais são os canais de atendimento?
O atendimento é feito pela área de Suporte aqui no painel (abra um chamado em "Suporte") e pelo e-mail contato@botapix.com. Ao abrir um chamado, descreva o ocorrido com o máximo de detalhes para agilizar a resposta.
---
# Introdução
Fonte: https://botapix.com/docs/introducao
# Introdução
A API do BotaPix permite cobrar via Pix a partir de qualquer aplicação. A cobrança é paga numa página hospedada pelo BotaPix, o valor é creditado no saldo da conta e a aplicação é notificada por webhook assim que o pagamento é confirmado.
## URL base
```text
https://botapix.com/api/v1
```
Todas as requisições usam HTTPS e são autenticadas com a API key da conta. Consulte [Autenticação](/docs/autenticacao).
## Recursos
- [Primeiros passos](/docs/primeiros-passos): Da API key à primeira cobrança paga, com exemplos em cURL, Node.js, PHP e Python.
- [Cobranças](/docs/cobrancas/criar): Pagamentos avulsos, como pedidos, ingressos e créditos.
- [Assinaturas](/docs/assinaturas/criar): Cobranças mensais recorrentes via Pix Automático.
- [Webhooks](/docs/webhooks/visao-geral): Notificações de pagamentos, devoluções e mudanças de status de assinaturas.
- [Explorar API](/docs/explorar): Todos os endpoints, parâmetros e respostas a partir da especificação OpenAPI.
- [Controle de alertas](/docs/streamers/controle-de-alertas): Controle remoto dos alertas exibidos em transmissões ao vivo.
## Fluxo de pagamento
1. A aplicação cria uma cobrança com [`POST /charges`](/docs/cobrancas/criar) e recebe a `payment_url`.
2. O pagador é redirecionado para a `payment_url` e paga com QR Code ou Pix Copia e Cola.
3. O BotaPix confirma o pagamento, credita o valor líquido e envia o evento [`payment.confirmed`](/docs/eventos/payment-confirmed).
4. A aplicação localiza o pedido pelo `external_reference` e conclui a venda.
## Próximos passos
- [Primeiros passos](/docs/primeiros-passos): do zero ao webhook no ambiente de testes.
- [Convenções](/docs/convencoes): valores, datas, paginação e formato das respostas.
- [Explorar API](/docs/explorar): todos os endpoints a partir da especificação OpenAPI.
---
# Primeiros passos
Fonte: https://botapix.com/docs/primeiros-passos
# Primeiros passos
Este guia leva uma cobrança avulsa do zero ao webhook no [ambiente de testes](/docs/ambientes-e-testes), sem movimentar dinheiro, e termina com a troca para produção. O código é o mesmo nos dois ambientes; muda apenas a chave.
## 1. Gere as credenciais de teste
Em [Dashboard → API](/dashboard/api), selecione **Teste** no seletor de ambiente. Na aba **Chaves**, crie uma chave de teste; na aba **Webhooks**, gere o secret de teste e cadastre a URL do seu endpoint. Os valores completos são exibidos uma única vez.
| Credencial | Prefixo | Uso |
|---|---|---|
| API key de teste | `btpx_test_` | Autentica as requisições no ambiente de testes. |
| Secret de webhook de teste | `whsec_test_` | Assina os eventos de teste enviados ao seu endpoint. |
Armazene as credenciais em variáveis de ambiente do servidor, como `BOTAPIX_API_KEY` e `BOTAPIX_WEBHOOK_SECRET`. As requisições à API devem partir sempre do servidor, nunca do navegador ou de aplicativos.
## 2. Crie a cobrança
Envie o valor em centavos e o identificador do pedido. A `Idempotency-Key` garante que uma nova tentativa, após falha de rede, não crie uma segunda cobrança.
```bash title="cURL"
curl https://botapix.com/api/v1/charges \
-H "Authorization: Bearer $BOTAPIX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido_1042" \
-d '{
"amount": 2990,
"external_reference": "pedido_1042",
"redirect_url": "https://loja.exemplo.com/pedidos/1042"
}'
```
```php title="PHP"
$client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']);
$response = $client->post('charges', [
'headers' => [
'Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY'),
'Idempotency-Key' => 'pedido_1042',
],
'json' => [
'amount' => 2990,
'external_reference' => 'pedido_1042',
'redirect_url' => 'https://loja.exemplo.com/pedidos/1042',
],
]);
$charge = json_decode($response->getBody(), true)['data'];
header('Location: ' . $charge['payment_url']);
```
```js title="Node.js"
const response = await fetch('https://botapix.com/api/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido_1042',
},
body: JSON.stringify({
amount: 2990,
external_reference: 'pedido_1042',
redirect_url: 'https://loja.exemplo.com/pedidos/1042',
}),
});
const { data: charge } = await response.json();
```
```python title="Python"
import os
import requests
response = requests.post(
"https://botapix.com/api/v1/charges",
headers={
"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}",
"Idempotency-Key": "pedido_1042",
},
json={
"amount": 2990,
"external_reference": "pedido_1042",
"redirect_url": "https://loja.exemplo.com/pedidos/1042",
},
)
charge = response.json()["data"]
```
```json title="201 Created"
{
"data": {
"id": 5021,
"reference": "sbx_Q4mZ8kT2vX7nB1cR9wL3pD6yH0sF",
"livemode": false,
"amount": 2990,
"status": "pending",
"payment_url": "https://botapix.com/pagar/sbx_Q4mZ8kT2vX7nB1cR9wL3pD6yH0sF",
"expires_at": "2026-09-13T15:30:00+00:00",
"created_at": "2026-09-13T14:30:00+00:00"
}
}
```
Redirecione o pagador para a `payment_url`. A página exibe o QR Code e o código Pix Copia e Cola e acompanha a confirmação em tempo real.
## 3. Simule o pagamento
No ambiente de testes, o pagamento é simulado. Abra a `payment_url` e use **Simular pagamento aprovado**, ou chame o endpoint de simulação com a chave de teste:
```bash title="cURL"
curl -X POST https://botapix.com/api/v1/sandbox/charges/5021/pay \
-H "Authorization: Bearer $BOTAPIX_API_KEY"
```
A cobrança passa a `paid` com a tarifa real da conta, e a página de pagamento mostra a confirmação e redireciona para a `redirect_url`.
## 4. Receba a confirmação
O endpoint cadastrado recebe o evento `payment.confirmed`, com `livemode: false` no ambiente de testes:
```json title="payment.confirmed"
{
"event": "payment.confirmed",
"event_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
"livemode": false,
"data": {
"id": 5021,
"reference": "sbx_Q4mZ8kT2vX7nB1cR9wL3pD6yH0sF",
"external_reference": "pedido_1042",
"source": "api",
"subscription_id": null,
"amount": 2990,
"amount_paid": 2990,
"fee": 90,
"net_amount": 2900,
"status": "paid",
"paid_at": "2026-09-13T14:35:12+00:00"
},
"timestamp": "2026-09-13T14:35:13+00:00"
}
```
Antes de processar o evento, o endpoint deve [verificar a assinatura](/docs/webhooks/assinatura-hmac) e descartar eventos já recebidos, identificados pelo `event_id`. A implementação completa está em [Configurar webhooks](/docs/webhooks/configurar#exemplo-de-endpoint).
> **Confirmação do pagamento**
>
> O retorno do pagador pela `redirect_url` não confirma o pagamento. Libere o pedido somente após o evento `payment.confirmed` ou após [consultar a cobrança](/docs/cobrancas/consultar) com status `paid`.
Chamar a simulação de novo numa cobrança paga reenvia o mesmo evento, com o mesmo `event_id`: confirme que o endpoint o descarta.
## 5. Vá para produção
1. Com **Produção** selecionado em [Dashboard → API](/dashboard/api), crie a chave de produção (`btpx_live_`), gere o secret de produção e cadastre o endpoint de produção.
2. Troque as variáveis de ambiente do servidor pelas credenciais de produção.
3. Crie uma cobrança de R$ 1,00 (`"amount": 100`) e conclua o pagamento pelo aplicativo de um banco.
4. Confirme o recebimento de `payment.confirmed` com `livemode: true`, o `external_reference` enviado e o redirecionamento para a `redirect_url`.
## Antes de publicar
- Credenciais armazenadas somente no servidor, fora do repositório.
- `Idempotency-Key` em todas as requisições de criação.
- Assinatura dos webhooks verificada sobre o corpo bruto da requisição.
- Eventos repetidos descartados pelo `event_id` e eventos desconhecidos respondidos com `200`.
- Respostas `429` e `5xx` tratadas com novas tentativas, conforme [Erros](/docs/erros).
- Credenciais de teste trocadas pelas de produção, e o `livemode` conferido nos eventos.
---
# Ambientes e testes
Fonte: https://botapix.com/docs/ambientes-e-testes
# Ambientes e testes
A conta tem dois ambientes. O ambiente é definido pela API key usada na requisição: a mesma integração roda nos dois trocando apenas a chave e o secret de webhook.
| | Produção | Teste |
|---|---|---|
| API key | `btpx_live_...` | `btpx_test_...` |
| Secret de webhook | `whsec_...` | `whsec_test_...` |
| Cobranças | Pagas com Pix de verdade | Pagas por simulação |
| Referência da cobrança | 32 caracteres | começa com `sbx_` |
| Saldo | Saldo da conta | Saldo simulado, separado |
| `livemode` nas respostas e eventos | `true` | `false` |
Os dados de um ambiente não aparecem no outro: uma chave de teste não consulta cobranças de produção, e vice-versa. Nada criado no ambiente de testes chega a uma instituição financeira ou movimenta o saldo da conta.
## Começar a testar
Em [Dashboard → API](/dashboard/api), selecione **Teste** no seletor de ambiente.
1. Na aba **Chaves**, crie uma chave de teste.
2. Na aba **Webhooks**, gere o secret de teste e cadastre um endpoint de teste. Para receber eventos na sua máquina, consulte [Testar localmente](/docs/webhooks/testar-localmente).
3. Crie cobranças com a chave de teste, exatamente como em [Criar cobrança](/docs/cobrancas/criar).
A aba **Cobranças de teste** também cria cobranças e executa as simulações sem código.
## Cobranças de teste
A cobrança de teste aceita os mesmos parâmetros, as mesmas validações e a mesma `Idempotency-Key` da produção. A resposta tem o mesmo formato, com `livemode: false`.
```json title="201 Created"
{
"data": {
"id": 5021,
"reference": "sbx_Q4mZ8kT2vX7nB1cR9wL3pD6yH0sF",
"livemode": false,
"amount": 2990,
"status": "pending",
"payment_url": "https://botapix.com/pagar/sbx_Q4mZ8kT2vX7nB1cR9wL3pD6yH0sF",
"expires_at": "2026-10-23T15:30:00+00:00",
"created_at": "2026-10-23T14:30:00+00:00"
}
}
```
A `payment_url` abre a página de pagamento com a faixa **Ambiente de testes** e os botões **Simular pagamento aprovado** e **Simular expiração**. Depois da simulação, a página segue o fluxo da produção: mostra a confirmação e redireciona para a `redirect_url`.
> **QR Code de teste**
>
> O QR Code e o Pix Copia e Cola de uma cobrança de teste não são pagáveis. O código começa com `BOTAPIX-SANDBOX-` e não é aceito por aplicativos de banco.
A tarifa aplicada é a mesma da conta em produção, para que `fee` e `net_amount` tenham os valores reais.
## Simulações
Os endpoints abaixo aceitam somente chave de teste. Com uma chave de produção, retornam `403` com `sandbox_only`.
| Método | Endpoint | Efeito | Evento |
|---|---|---|---|
| `POST` | `/v1/sandbox/charges/{id}/pay` | Marca a cobrança como paga. `amount_paid` opcional, em centavos, simula pagamento de outro valor. | `payment.confirmed` |
| `POST` | `/v1/sandbox/charges/{id}/expire` | Vence a cobrança. | `payment.expired` |
| `POST` | `/v1/sandbox/charges/{id}/refund` | Devolve parte ou todo o valor. `amount` opcional, em centavos. | `payment.refunded`, somente na devolução integral |
| `GET` | `/v1/sandbox/balance` | Saldo simulado das cobranças de teste. | |
O `{id}` aceita o ID numérico ou a `reference`.
### Assinaturas de teste
[Criar assinatura](/docs/assinaturas/criar) com chave de teste cria uma assinatura de teste, com as mesmas validações e `livemode: false`. O copia-e-cola de autorização não é pagável. O que na produção vem do banco do pagador é simulado:
| Método | Endpoint | Efeito | Evento |
|---|---|---|---|
| `POST` | `/v1/sandbox/subscriptions/{id}/authorize` | O pagador autoriza: `active`. | `subscription.activated` |
| `POST` | `/v1/sandbox/subscriptions/{id}/reject` | O pagador recusa: `rejected`. | `subscription.rejected` |
| `POST` | `/v1/sandbox/subscriptions/{id}/cycles/next/pay` | Debita o próximo ciclo com a tarifa de assinatura real e avança `next_cycle_date` em um mês. | `payment.confirmed` com `source: subscription` |
| `POST` | `/v1/sandbox/subscriptions/{id}/cancel-by-payer` | O pagador cancela: `canceled`. | `subscription.canceled` |
A cobrança de cada ciclo debitado aparece em [Listar cobranças](/docs/cobrancas/listar) da chave de teste, com `source: subscription` e o `subscription_id`.
```bash title="cURL"
curl -X POST https://botapix.com/api/v1/sandbox/charges/5021/pay \
-H "Authorization: Bearer $BOTAPIX_API_KEY"
```
As simulações retornam a cobrança no formato de [Consultar cobrança](/docs/cobrancas/consultar). Uma cobrança já paga, expirada ou devolvida retorna `409` com `invalid_state` quando a transição não é permitida.
### Testar eventos repetidos
Chamar `pay` numa cobrança que já está paga reenvia o mesmo `payment.confirmed`, com o mesmo `event_id`. Use para confirmar que o endpoint descarta eventos já processados, como descrito em [Configurar webhooks](/docs/webhooks/configurar#exemplo-de-endpoint).
## Webhooks de teste
Os eventos do ambiente de testes têm `livemode: false`, são assinados com o secret de teste e vão somente para os endpoints de teste, ou para a `notification_url` da cobrança. Nunca são enviados a um endpoint de produção. Usar `notification_url` numa cobrança de teste exige o secret de teste gerado.
As entregas aparecem no log **Entregas** da aba Webhooks, com o ambiente de testes selecionado.
## Limites
- Chaves de teste têm limite de 120 requisições por minuto em cada grupo de endpoints. O ambiente de testes não é indicado para teste de carga.
- Cobranças, assinaturas e entregas de webhook de teste são apagadas após 30 dias. A aba **Cobranças de teste** permite apagá-las antes.
## Ir para produção
1. Crie uma chave de produção e gere o secret de produção.
2. Cadastre o endpoint de produção na aba Webhooks, com o ambiente **Produção** selecionado.
3. Troque as variáveis de ambiente do servidor pelas credenciais de produção. O código não muda.
4. Valide com uma cobrança real de R$ 1,00 (`"amount": 100`), paga pelo aplicativo de um banco.
---
# Autenticação
Fonte: https://botapix.com/docs/autenticacao
# Autenticação
As requisições são autenticadas com a API key da conta, enviada no header `Authorization` como token Bearer.
```http
Authorization: Bearer btpx_...
```
## API keys
As chaves são criadas em [Dashboard → API](/dashboard/api), mediante confirmação de senha, cada uma com um nome e uma permissão. A conta pode ter até 10 chaves ativas em cada ambiente: use uma por sistema (site, servidor, unidade), para revogar uma sem afetar as outras.
| Ambiente | Prefixo | Acesso |
|---|---|---|
| Produção | `btpx_live_` | Cobranças e assinaturas reais. Chaves criadas antes de outubro de 2026 começam com `btpx_` e continuam válidas. |
| Teste | `btpx_test_` | Somente o [ambiente de testes](/docs/ambientes-e-testes). |
O valor completo da chave é exibido somente no momento da criação. A BotaPix guarda apenas uma impressão (hash) da chave; o dashboard mostra o nome, o prefixo e os quatro últimos caracteres. Se a chave for perdida, crie outra e revogue a anterior.
Revogar uma chave tem efeito imediato: requisições com ela passam a receber `401`. As demais chaves da conta continuam funcionando.
Mantenha as chaves no servidor, em variável de ambiente ou cofre de segredos, e nunca as inclua em aplicações cliente, repositórios ou logs.
### Permissões
Cada chave é criada com um conjunto de permissões:
| Conjunto | Permissões | Uso |
|---|---|---|
| Recebimentos | `charges:write`, `charges:read`, `subscriptions:write`, `subscriptions:read` | Servidor que cria cobranças e assinaturas. |
| Loja | `charges:write`, `charges:read`, `products:read`, `products:write` | Sistema da loja: catálogo, estoque de chaves, venda e entrega de produtos. |
| Somente leitura | `charges:read`, `subscriptions:read`, `balance:read`, `withdrawals:read`, `disputes:read` | Relatórios e conciliação. |
| Financeiro | `charges:read`, `balance:read`, `withdrawals:read`, `withdrawals:write`, `refunds:write`, `disputes:read` | Sistema financeiro: saldo, extrato, saques, devoluções e disputas. |
| Permissão | Endpoints |
|---|---|
| `charges:write` | `POST /charges` |
| `charges:read` | `GET /charges`, `GET /charges/{id}`, `GET /charges/stats`, `GET /charges/{id}/refunds` |
| `subscriptions:write` | `POST /subscriptions`, `DELETE /subscriptions/{id}` |
| `subscriptions:read` | `GET /subscriptions`, `GET /subscriptions/{id}` |
| `balance:read` | `GET /balance`, `GET /statement` |
| `withdrawals:write` | `POST /withdrawals` |
| `withdrawals:read` | `GET /withdrawals`, `GET /withdrawals/{id}` |
| `refunds:write` | `POST /charges/{id}/refunds` |
| `disputes:read` | `GET /disputes`, `GET /disputes/{id}` |
| `products:write` | `POST /products`, `PATCH /products/{id}`, `DELETE /products/{id}`, `POST /products/{id}/keys` |
| `products:read` | `GET /products`, `GET /products/{id}`, `GET /charges/{id}/delivery` |
Uma chave sem a permissão necessária recebe `403` com `error` igual a `insufficient_scope`. As permissões de produtos ficam fora da chave **Somente leitura** porque a entrega traz as chaves e os links recebidos pelo comprador.
### Trocar uma chave sem interrupção
1. Crie uma chave nova com a mesma permissão.
2. Atualize a variável de ambiente da integração com a chave nova.
3. Confirme no dashboard que a chave nova aparece como usada.
4. Revogue a chave anterior.
## Respostas de autenticação
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | Header ausente, mal formatado, ou API key inválida ou revogada. |
| `403` | `forbidden` | Conta suspensa ou bloqueada. |
| `403` | `insufficient_scope` | A chave não tem a permissão exigida pelo endpoint. |
| `403` | `sandbox_only` | Endpoint de simulação chamado com chave de produção. |
| `403` | `test_mode_unsupported` | Recurso sem ambiente de testes (saques, disputas e produtos) chamado com chave de teste. |
## Limites de requisições
Os limites são aplicados por API key, em janelas de um minuto. Endpoints do mesmo grupo compartilham o contador.
| Grupo | Endpoints | Limite por minuto |
|---|---|---|
| Criação | `POST /charges`, `POST /subscriptions` | 600 |
| Consulta e demais operações | Consulta de cobranças e assinaturas, `DELETE /subscriptions/{id}`, saldo, extrato, devoluções, disputas, produtos e consulta de saques | 200 |
`POST /withdrawals` tem limite próprio: 10 saques por hora por conta.
Chaves de teste têm limite de 120 requisições por minuto em cada grupo, incluindo os endpoints de simulação.
Há também um teto por endereço IP, somando todas as API keys que chamam do mesmo servidor: 1.800 criações e 1.200 consultas por minuto. Uma integração com uma única API key nunca chega nele.
As respostas autenticadas informam o consumo da janela atual:
| Header | Descrição |
|---|---|
| `X-RateLimit-Limit` | Limite do grupo por minuto. |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual. |
| `Retry-After` | Segundos até a liberação. Enviado com `429`. |
Ao exceder o limite, a API responde `429 Too Many Requests`. Aguarde o tempo indicado em `Retry-After` antes de repetir a requisição. Os [controles de alerta](/docs/streamers/controle-de-alertas) usam um token próprio, com limites próprios.
---
# Antes de ir para produção
Fonte: https://botapix.com/docs/antes-de-producao
# Antes de ir para produção
Marque cada item conforme a integração atende. O estado fica salvo neste navegador.
## Credenciais
- [ ] API key e secret de webhook de produção em variáveis de ambiente do servidor, fora do repositório e dos logs.
- [ ] Requisições à API feitas somente pelo servidor, nunca pelo navegador ou por aplicativos.
- [ ] Uma chave por sistema, com a [permissão](/docs/autenticacao#permissoes) mínima necessária.
- [ ] Procedimento definido para [trocar uma chave](/docs/autenticacao#trocar-uma-chave-sem-interrupcao) e o [secret de webhook](/docs/webhooks/configurar#troca-do-secret) sem interrupção.
## Cobranças
- [ ] `Idempotency-Key` em todas as requisições de criação, derivada do identificador do pedido.
- [ ] `external_reference` com o identificador do pedido, para conciliar.
- [ ] `expiration` adequado ao fluxo: prazos curtos reduzem a conversão quando o pagador precisa abrir outro aplicativo.
- [ ] Pedido liberado somente após `payment.confirmed` ou consulta com status `paid`, nunca pelo retorno da `redirect_url`.
## Webhooks
- [ ] Assinatura verificada sobre o corpo bruto da requisição, com comparação em tempo constante.
- [ ] Eventos repetidos descartados pelo `event_id`.
- [ ] Resposta `2xx` em até 10 segundos, com o processamento em fila.
- [ ] Tipos de evento desconhecidos respondidos com `200`.
- [ ] `livemode` conferido: eventos de teste não alteram pedidos de produção.
- [ ] Endpoint de produção cadastrado com o ambiente **Produção** selecionado e testado com **Enviar teste**.
## Erros e conciliação
- [ ] Respostas `429` e `5xx` tratadas com novas tentativas e espera crescente, conforme [Erros](/docs/erros).
- [ ] Conciliação periódica com [Listar cobranças](/docs/cobrancas/listar), para recuperar eventos não recebidos.
- [ ] Uma cobrança real de R$ 1,00 paga pelo aplicativo de um banco, com o `payment.confirmed` recebido.
---
# Convenções
Fonte: https://botapix.com/docs/convencoes
# Convenções
Regras que valem para todos os endpoints da API.
## Requisições
| Item | Padrão |
|---|---|
| URL base | `https://botapix.com/api/v1` |
| Protocolo | HTTPS. Requisições HTTP são recusadas. |
| Autenticação | `Authorization: Bearer` com a API key. Consulte [Autenticação](/docs/autenticacao). |
| Corpo | JSON, com `Content-Type: application/json`. |
| Idempotência | Header `Idempotency-Key` opcional nas criações. Consulte [Idempotência](/docs/cobrancas/idempotencia). |
## Respostas
O recurso vem em `data`. Listas paginadas incluem `meta`:
```json title="200 OK"
{
"data": [
{ "id": 1042, "reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe", "livemode": true, "amount": 2990, "status": "paid" }
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 52
}
}
```
Erros têm `error` (código estável, para tratar no código) e `message` (texto para pessoas). Consulte [Erros](/docs/erros).
Novos atributos podem ser adicionados às respostas e aos eventos. A aplicação deve ignorar atributos que não conhece.
## Valores
| Item | Padrão |
|---|---|
| Dinheiro | Inteiro em centavos. `2990` é R$ 29,90. Vale para requisições, respostas e eventos. |
| Data e hora | ISO 8601 em UTC, como `2026-10-23T14:30:00+00:00`. |
| Data | `YYYY-MM-DD`. Filtros de data (`from`, `to`) consideram o dia inteiro. |
| Booleanos | `true` ou `false`, nunca texto. |
## Identificadores
| Atributo | Descrição |
|---|---|
| `id` | Número sequencial da cobrança ou da assinatura na conta. |
| `reference` | Identificador público. Cobranças de produção têm 32 caracteres; as de teste começam com `sbx_`, e as assinaturas de teste com `sbx_rec_`. |
| `external_reference` | O identificador do seu sistema, enviado na criação. Use para conciliar. |
| `event_id` | Identificador de um evento de webhook, igual em todas as tentativas e em todos os endpoints. |
Os endpoints de consulta aceitam o `id` ou a `reference` no caminho.
## Paginação
As listas aceitam `limit` (padrão 20, máximo 100; valores maiores são reduzidos para 100) e `page`. A ordem é da mais recente para a mais antiga, e o desempate é pelo `id`, para que as páginas sejam estáveis durante a conciliação.
## Ambiente
Toda cobrança, assinatura e evento informa `livemode`: `true` em produção e `false` no [ambiente de testes](/docs/ambientes-e-testes). O ambiente é definido pela API key da requisição.
## Especificação OpenAPI
A especificação completa, no formato OpenAPI 3.1, está em [`/docs/openapi.json`](/docs/openapi.json) e pode ser importada em ferramentas como Postman e Insomnia. A mesma especificação alimenta o [Explorar API](/docs/explorar).
---
# Integrando com IA
Fonte: https://botapix.com/docs/integrando-com-ia
# Integrando com IA
A documentação é publicada também em formatos que assistentes de IA leem bem. Use-os para gerar e revisar o código da integração.
## Formatos disponíveis
| Formato | Endereço | Uso |
|---|---|---|
| Markdown de uma página | Acrescente `.md` ao endereço, como [`/docs/cobrancas/criar.md`](/docs/cobrancas/criar.md) | Contexto de uma tarefa específica. |
| Índice | [`/llms.txt`](/llms.txt) | Lista de todas as páginas, com descrição. |
| Documentação completa | [`/llms-full.txt`](/llms-full.txt) | Todas as páginas num arquivo só. |
| Especificação | [`/docs/openapi.json`](/docs/openapi.json) | Endpoints, parâmetros, respostas e eventos em OpenAPI 3.1. |
Em cada página, o botão **Copiar página** copia a versão em Markdown, e o menu ao lado abre uma conversa no ChatGPT ou no Claude já apontando para ela.
## Prompt de partida
```text title="Prompt"
Leia https://botapix.com/llms-full.txt e a especificação em
https://botapix.com/docs/openapi.json. Escreva, em [linguagem e framework],
a integração com a API do BotaPix para:
1. criar uma cobrança com Idempotency-Key derivada do ID do pedido e
redirecionar o pagador para a payment_url;
2. receber o webhook payment.confirmed, verificar o X-BotaPix-Signature
sobre o corpo bruto, descartar eventos repetidos pelo event_id e
liberar o pedido pelo external_reference.
Leia as credenciais de variáveis de ambiente. Use o ambiente de testes
(chave btpx_test_) e mostre como simular o pagamento.
```
## Cuidados
- Não cole API keys nem o secret de webhook numa conversa. Use variáveis de ambiente no código gerado.
- Gere e teste o código com a chave de teste. As cobranças de teste não movimentam dinheiro.
- Confira o código gerado contra as páginas de referência, em especial a verificação de assinatura e a idempotência.
---
# Erros
Fonte: https://botapix.com/docs/erros
# Erros
A API usa status HTTP convencionais: `2xx` indica sucesso, `4xx` indica um problema na requisição e `5xx` indica uma falha no BotaPix.
## Formato
Erros retornam um código estável em `error`, indicado para tratamento programático, e uma descrição em `message`, que pode mudar sem aviso.
```json title="404 Not Found"
{
"error": "not_found",
"message": "Cobrança não encontrada."
}
```
Erros de validação retornam `422` com a lista de problemas por campo em `errors`, sem o campo `error`:
```json title="422 Unprocessable Content"
{
"message": "O campo amount deve ser pelo menos 100.",
"errors": {
"amount": ["O campo amount deve ser pelo menos 100."]
}
}
```
## Códigos de erro
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | API key ausente, mal formatada, inválida ou revogada. |
| `403` | `forbidden` | Conta suspensa ou bloqueada. |
| `403` | `insufficient_scope` | A API key não tem a permissão exigida pelo endpoint. Consulte [Permissões](/docs/autenticacao#permissoes). |
| `403` | `kyc_required` | Recebimentos indisponíveis para a conta. Afeta a criação de cobranças e assinaturas de produção. |
| `403` | `test_mode_unsupported` | Recurso sem ambiente de testes (saques, disputas e produtos) chamado com chave de teste. |
| `403` | `sandbox_only` | Endpoint de simulação chamado com chave de produção. Consulte [Ambientes e testes](/docs/ambientes-e-testes). |
| `404` | `not_found` | Recurso inexistente ou pertencente a outra conta. |
| `404` | `product_not_found` | `product_id` da cobrança não encontrado na conta. |
| `404` | `delivery_not_found` | Cobrança sem venda de produto, ou ainda não paga. |
| `409` | `pix_key_missing` | Saque solicitado sem chave Pix cadastrada na conta. |
| `409` | `pix_key_invalid` | A chave Pix cadastrada na conta não é válida. |
| `409` | `invalid_state` | Simulação não permitida no status atual da cobrança de teste, ou devolução de cobrança não paga. |
| `409` | `already_refunded` | Cobrança já devolvida integralmente. |
| `409` | `dispute_open` | Devolução de cobrança com disputa (MED) aberta. |
| `409` | `refund_not_available` | Pagamento que não pode ser devolvido pela API. |
| `409` | `product_unavailable` | Venda de produto inativo ou suspenso. |
| `409` | `out_of_stock` | Estoque do produto insuficiente. A resposta traz `available`. |
| `409` | `keys_not_supported` | Chaves enviadas para um produto que não entrega chaves. |
| `422` | | Parâmetros inválidos. Os campos estão em `errors`. |
| `422` | `idempotency_key_reused` | `Idempotency-Key` já utilizada com outro corpo. |
| `422` | `invalid_idempotency_key` | `Idempotency-Key` com mais de 255 caracteres, fora de UTF-8 ou com caracteres de controle. |
| `422` | `psp_rejected` | Assinatura recusada pela instituição financeira. |
| `422` | `invalid_state` | Assinatura já cancelada ou recusada. |
| `422` | `insufficient_balance` | Saldo disponível menor que o saque ou a devolução. A resposta traz `available`. |
| `422` | `refund_not_supported` | Devolução de ciclo de assinatura. |
| `422` | `refund_window_expired` | Devolução de pagamento feito há mais de 30 dias. |
| `422` | `amount_too_low_for_fee` | O saque seria zero depois da tarifa. |
| `422` | `amount_mismatch` | `amount` diferente do preço do produto vezes `quantity`. A resposta traz `expected_amount`. |
| `422` | `invalid_quantity` | `quantity` acima do `max_per_order` do produto. |
| `422` | `product_limit_reached` | A conta já tem 200 produtos. |
| `422` | `store_identification_required` | Criação ou alteração de produto sem a [loja identificada](/docs/produtos/catalogo#identificacao-da-loja). |
| `422` | `seller_terms_required` | Criação ou alteração de produto sem as regras de venda aceitas no painel. |
| `422` | `invalid_amount` | Valor fora do permitido numa devolução ou simulação. Nas devoluções, a resposta traz `refundable`. |
| `429` | | Limite de requisições excedido. Consulte o header `Retry-After`. |
| `500` | `internal_error` | Falha ao criar a cobrança ou a assinatura. Nenhum valor foi cobrado. |
Falhas inesperadas em qualquer endpoint retornam `500` e podem conter apenas `message`.
## Recusa pela instituição financeira
Em `psp_rejected`, o campo `violations` indica o que foi recusado. Os nomes em `field` seguem a nomenclatura do Pix Automático: `rec.vinculo.objeto` corresponde a `description` e `rec.vinculo.devedor` corresponde a `customer`.
```json title="422 Unprocessable Content"
{
"error": "psp_rejected",
"message": "O banco recusou a criação da assinatura: A requisição que busca alterar ou criar uma recorrência não respeita o schema ou está semanticamente errada.",
"violations": [
{ "field": "body.rec.vinculo.objeto", "reason": "O campo rec.vinculo.objeto não respeita o schema." }
]
}
```
## Novas tentativas
Repita somente requisições que retornaram `429` ou `5xx`, com intervalos crescentes entre as tentativas. Nas requisições de criação, reutilize a mesma `Idempotency-Key`: se a requisição anterior tiver sido concluída, a API retorna o recurso já criado.
---
# Changelog
Fonte: https://botapix.com/docs/changelog
# Changelog
Atributos e eventos novos podem aparecer a qualquer momento: a aplicação deve ignorar o que não conhece.
## Novembro de 2026
### Produtos
- Criar e alterar produtos passa a exigir a [loja identificada](/docs/produtos/catalogo#identificacao-da-loja) (nome e um contato para o comprador) e as regras de venda aceitas no painel. Sem elas, `POST /products` e `PATCH /products/{id}` retornam `422` com `store_identification_required` ou `seller_terms_required`. Consultas, chaves, remoção e venda de produtos existentes não mudam.
- Atributo `suspended` no produto. Um produto suspenso pelo BotaPix retorna `409 product_unavailable` na venda.
## Outubro de 2026
### Origem de campanha
- Objeto `tracking` (UTMs, `fbclid` e `gclid`) em [Criar cobrança](/docs/cobrancas/criar), na consulta e nos eventos `payment.*`. Links de produto, páginas de doação e vaquinhas capturam as UTMs da URL sozinhos.
### Produtos
- [Catálogo de produtos](/docs/produtos/catalogo) com entrega automática por texto, link ou chave de licença, e estoque de chaves.
- [Venda pela API](/docs/produtos/vender) com `product_id` e `quantity` em `POST /charges`, e a entrega em `GET /charges/{id}/delivery`.
- Atributo `product` em cobranças e eventos `payment.*`; origem `product` para compras pelo link.
- Eventos `delivery.completed` e `delivery.failed`. Permissões `products:read` e `products:write`, na nova chave **Loja**.
### Ambiente de testes
- Chaves de teste (`btpx_test_`), cobranças e assinaturas de teste e simulações de pagamento, expiração, devolução, autorização e ciclo. Consulte [Ambientes e testes](/docs/ambientes-e-testes).
- Página de pagamento de teste com simulação, e **Testar agora** nas páginas de referência.
- Atributo `livemode` em cobranças, assinaturas e eventos.
### Dinheiro
- [Saldo e extrato](/docs/dinheiro/saldo-e-extrato), [saques](/docs/dinheiro/saques) para a chave Pix da conta e [devoluções](/docs/dinheiro/devolucoes) totais ou parciais e [disputas (MED)](/docs/dinheiro/disputas).
- Eventos `withdrawal.*`, `refund.*` e `dispute.*`.
### Webhooks
- Até 5 endpoints por ambiente, cada um com os eventos que escolher.
- Troca do secret em duas etapas, sem interrupção.
- Log de entregas no dashboard, com reenvio.
- Desativação automática de endpoints com 50 falhas seguidas.
- Evento [`payment.expired`](/docs/eventos/payment-expired).
### Chaves de API
- Várias chaves por conta, com nome e permissão (recebimentos, somente leitura ou financeiro). Novas chaves começam com `btpx_live_`; as anteriores, com `btpx_`, continuam válidas.
- Erro `insufficient_scope` para chave sem a permissão do endpoint.
### Cobranças e assinaturas
- Campo `pix` com QR Code e copia-e-cola na resposta da cobrança, para contas com a exibição liberada. Consulte [Exibir o QR no seu site](/docs/cobrancas/exibir-qr).
- `notification_url` e `metadata` por cobrança.
- `current_cycle` e `next_cycle_date` nas assinaturas.
- A listagem de cobranças trata pendentes vencidas como `expired`; `redirect_url` aceita somente `http` e `https`.
- Filtro `status` inválido em `GET /subscriptions` retorna `422`.
## Setembro de 2026
- `Idempotency-Key` comparada byte a byte; chave inválida retorna `422` com `invalid_idempotency_key`.
- Eventos de assinatura: `subscription.activated`, `subscription.rejected` e `subscription.canceled`.
- Evento de teste pelo dashboard.
- Atributo `source` nas cobranças e nos eventos, também como filtro.
- Especificação OpenAPI e [Explorar API](/docs/explorar).
---
# Criar cobrança
Fonte: https://botapix.com/docs/cobrancas/criar
# Criar cobrança
`POST https://botapix.com/api/v1/charges`
A cobrança fica disponível para pagamento até `expires_at` e aceita um único pagamento. O pagador conclui o Pix na página hospedada em `payment_url`, que exibe o QR Code, o código Pix Copia e Cola e o prazo restante, e acompanha a confirmação em tempo real. Por padrão a página não identifica a conta; com o **checkout com a sua marca** ligado em Dashboard → Configurações, ela mostra o nome, o logo, a cor e o contato de suporte da loja.
Quando o pagamento é confirmado, a cobrança passa para `paid`, o valor líquido é creditado no saldo da conta e o evento [`payment.confirmed`](/docs/eventos/payment-confirmed) é enviado.
```bash title="cURL"
curl https://botapix.com/api/v1/charges \
-H "Authorization: Bearer $BOTAPIX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido_1042" \
-d '{
"amount": 2990,
"external_reference": "pedido_1042",
"description": "Pedido #1042",
"expiration": 1800,
"redirect_url": "https://loja.exemplo.com/pedidos/1042",
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com",
"document": "12345678909"
},
"metadata": {"loja": "centro", "canal": "site"}
}'
```
```php title="PHP"
$client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']);
$response = $client->post('charges', [
'headers' => [
'Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY'),
'Idempotency-Key' => 'pedido_1042',
],
'json' => [
'amount' => 2990,
'external_reference' => 'pedido_1042',
'description' => 'Pedido #1042',
'expiration' => 1800,
'redirect_url' => 'https://loja.exemplo.com/pedidos/1042',
'customer' => [
'name' => 'João Silva',
'email' => 'joao@exemplo.com',
'document' => '12345678909',
],
'metadata' => ['loja' => 'centro', 'canal' => 'site'],
],
]);
$charge = json_decode($response->getBody(), true)['data'];
```
```js title="Node.js"
const response = await fetch('https://botapix.com/api/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido_1042',
},
body: JSON.stringify({
amount: 2990,
external_reference: 'pedido_1042',
description: 'Pedido #1042',
expiration: 1800,
redirect_url: 'https://loja.exemplo.com/pedidos/1042',
customer: { name: 'João Silva', email: 'joao@exemplo.com', document: '12345678909' },
metadata: { loja: 'centro', canal: 'site' },
}),
});
const { data: charge } = await response.json();
```
```python title="Python"
import os
import requests
response = requests.post(
"https://botapix.com/api/v1/charges",
headers={
"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}",
"Idempotency-Key": "pedido_1042",
},
json={
"amount": 2990,
"external_reference": "pedido_1042",
"description": "Pedido #1042",
"expiration": 1800,
"redirect_url": "https://loja.exemplo.com/pedidos/1042",
"customer": {"name": "João Silva", "email": "joao@exemplo.com", "document": "12345678909"},
"metadata": {"loja": "centro", "canal": "site"},
},
)
charge = response.json()["data"]
```
```json title="201 Created"
{
"data": {
"id": 1042,
"reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"amount": 2990,
"status": "pending",
"payment_url": "https://botapix.com/pagar/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"expires_at": "2026-09-13T15:00:00+00:00",
"created_at": "2026-09-13T14:30:00+00:00"
}
}
```
## Headers
- `Authorization` (string, obrigatório): `Bearer` seguido da API key. Consulte [Autenticação](/docs/autenticacao).
- `Idempotency-Key` (string): Chave única da operação, com até 255 caracteres. Uma requisição repetida com a mesma chave e o mesmo corpo retorna a cobrança original. Consulte [Idempotência](/docs/cobrancas/idempotencia).
## Corpo da requisição
- `amount` (integer, obrigatório): Valor em centavos. Mínimo de `100`, máximo de `9999999999`. Opcional com `product_id`.
- `product_id` (string): Vende um produto do catálogo: o valor vem do preço, o estoque é reservado e a entrega é automática. Consulte [Vender um produto](/docs/produtos/vender).
- `quantity` (integer): Unidades do produto, de `1` a `100`, limitadas ao `max_per_order` dele. Exige `product_id`.
- `external_reference` (string): Identificador do pedido na sua aplicação. Retornado nas consultas e nos webhooks. Até 255 caracteres.
- `description` (string): Mensagem exibida ao pagador no aplicativo do banco no momento do pagamento. Até 140 caracteres.
- `expiration` (integer): Prazo para pagamento, em segundos, de `300` a `86400`. Padrão: `3600`. Em pagamento presencial, use de 15 a 30 minutos: prazos menores costumam expirar antes de o pagador concluir o Pix.
- `redirect_url` (string): URL `http` ou `https` para onde o pagador é redirecionado após a confirmação do pagamento. Até 500 caracteres.
- `notification_url` (string): URL que recebe os eventos desta cobrança, no lugar dos endpoints da conta. Indicada quando mais de um sistema, como unidades ou caixas, usa a mesma conta. HTTPS na porta 443 ou 8443, até 500 caracteres. Os eventos são assinados com o secret de webhook do ambiente. Consulte [URL por cobrança](/docs/webhooks/configurar#url-por-cobranca).
- `customer` (object): Dados do pagador, usados para identificação nas consultas. Não são exibidos na página de pagamento.
- `customer.name` (string): Nome do pagador. Até 100 caracteres.
- `customer.email` (string): E-mail do pagador. Até 255 caracteres.
- `customer.document` (string): CPF ou CNPJ do pagador, com ou sem máscara. Armazenado somente com os dígitos.
- `metadata` (object): Dados livres para identificar a cobrança na sua aplicação, como loja, caixa ou canal. Retornado sem alteração na consulta, na listagem e nos eventos de pagamento. Até 20 chaves com até 40 caracteres (letras, números, `.`, `-` e `_`). Valores de texto, número, booleano ou `null`; texto com até 500 caracteres.
- `tracking` (object): Origem de campanha da venda: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` e `utm_content` (até 100 caracteres cada), `fbclid` e `gclid` (até 255). Outros campos são ignorados. Retornado na consulta e nos eventos de pagamento.
## Resposta
Retorna `201 Created` com a cobrança. Uma requisição repetida com a mesma `Idempotency-Key` retorna `200 OK` com a cobrança original.
- `id` (integer): Identificador da cobrança.
- `reference` (string): Identificador público da cobrança, com 32 caracteres. Aceito em [Consultar cobrança](/docs/cobrancas/consultar).
- `amount` (integer): Valor em centavos.
- `status` (string): `pending` na criação. Os demais status estão em [Consultar cobrança](/docs/cobrancas/consultar#status).
- `payment_url` (string): URL da página de pagamento.
- `pix` (object, condicional): QR Code e código Pix Copia e Cola para exibir no seu site, app ou jogo. Presente somente em contas com o checkout transparente ativo e enquanto a cobrança aceita pagamento. Consulte [Exibir o QR no seu site](/docs/cobrancas/exibir-qr).
- `pix.copia_e_cola` (string): Código Pix Copia e Cola.
- `pix.qr_code` (string): Imagem do QR Code em SVG, como data URI (`data:image/svg+xml;base64,...`).
- `expires_at` (string): Data e hora limite para pagamento.
- `created_at` (string): Data e hora de criação.
> **Confirmação do pagamento**
>
> O redirecionamento para `redirect_url` não confirma o pagamento. Libere o pedido somente após o evento `payment.confirmed` ou após [consultar a cobrança](/docs/cobrancas/consultar) com status `paid`.
## Erros
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | API key ausente ou inválida. |
| `403` | `kyc_required` | Recebimentos indisponíveis para a conta. |
| `403` | `test_mode_unsupported` | `product_id` enviado com chave de teste. |
| `404` | `product_not_found` | `product_id` não encontrado na conta. |
| `409` | `product_unavailable` | Produto inativo ou suspenso. |
| `409` | `out_of_stock` | Estoque insuficiente. A resposta traz `available`. |
| `422` | | Parâmetros inválidos. Os campos estão em `errors`. |
| `422` | `idempotency_key_reused` | `Idempotency-Key` já utilizada com outro corpo. |
| `422` | `invalid_idempotency_key` | `Idempotency-Key` com mais de 255 caracteres, fora de UTF-8 ou com caracteres de controle. |
| `422` | `webhook_secret_required` | `notification_url` informada sem secret de webhook gerado na conta. |
| `422` | `amount_mismatch` | `amount` diferente do preço do produto vezes `quantity`. A resposta traz `expected_amount`. |
| `422` | `invalid_quantity` | `quantity` acima do `max_per_order` do produto. |
| `429` | | Limite de requisições excedido. |
| `500` | `internal_error` | Cobrança não criada. A requisição pode ser repetida com a mesma `Idempotency-Key`. |
---
# Consultar cobrança
Fonte: https://botapix.com/docs/cobrancas/consultar
# Consultar cobrança
`GET https://botapix.com/api/v1/charges/{id}`
Retorna o estado atual da cobrança, incluindo valor pago, tarifa e valor líquido. A consulta complementa o webhook: use-a para conferir um pedido antes de liberá-lo ou para conciliar cobranças após uma indisponibilidade do seu endpoint.
```bash title="cURL"
curl "https://botapix.com/api/v1/charges/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe" \
-H "Authorization: Bearer $BOTAPIX_API_KEY"
```
```php title="PHP"
$client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']);
$response = $client->get('charges/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe', [
'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```
```js title="Node.js"
const response = await fetch('https://botapix.com/api/v1/charges/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe', {
headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}` },
});
const result = await response.json();
```
```python title="Python"
import os
import requests
response = requests.get(
"https://botapix.com/api/v1/charges/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
headers={"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}"},
)
result = response.json()
```
```json title="200 OK"
{
"data": {
"id": 1042,
"reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"external_reference": "pedido_1042",
"source": "api",
"subscription_id": null,
"product": null,
"amount": 2990,
"amount_paid": 2990,
"fee": 90,
"net_amount": 2900,
"status": "paid",
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com"
},
"metadata": {"loja": "centro", "canal": "site"},
"tracking": null,
"notification_url": null,
"paid_at": "2026-09-13T14:35:12+00:00",
"expires_at": "2026-09-13T15:00:00+00:00",
"created_at": "2026-09-13T14:30:00+00:00"
}
}
```
## Parâmetros de rota
- `id` (string, obrigatório): `id` numérico ou `reference` da cobrança.
## Resposta
- `id` (integer): Identificador da cobrança.
- `reference` (string): Identificador público da cobrança, com 32 caracteres.
- `external_reference` (string, nulo): Identificador informado na criação.
- `source` (string): Origem da cobrança: `api`, `subscription`, `dashboard`, `donation`, `campaign`, `product` ou `discord`. Consulte [Origem](/docs/webhooks/eventos#origem-do-pagamento).
- `subscription_id` (integer, nulo): Assinatura vinculada, quando `source` é `subscription`.
- `product` (object, nulo): Produto vendido, com `id` e `quantity`, quando a cobrança é a [venda de um produto](/docs/produtos/vender).
- `amount` (integer): Valor da cobrança, em centavos.
- `amount_paid` (integer, nulo): Valor pago, em centavos.
- `fee` (integer): Tarifa, em centavos.
- `net_amount` (integer): Valor líquido creditado no saldo, em centavos.
- `status` (string): Status da cobrança. Consulte [Status](#status).
- `pix` (object, condicional): QR Code e código Pix Copia e Cola, com os campos `copia_e_cola` e `qr_code`. Presente somente em contas com o checkout transparente ativo e enquanto a cobrança está `pending` dentro do prazo. Consulte [Exibir o QR no seu site](/docs/cobrancas/exibir-qr).
- `customer` (object): Dados do pagador informados na criação.
- `customer.name` (string, nulo): Nome do pagador.
- `customer.email` (string, nulo): E-mail do pagador.
- `metadata` (object, nulo): O `metadata` informado na criação.
- `tracking` (object, nulo): Origem de campanha: as UTMs e os ids de clique (`fbclid`, `gclid`) enviados na criação ou capturados da URL do link de produto, da página de doação ou da vaquinha.
- `notification_url` (string, nulo): URL de eventos própria da cobrança, ou `null` quando os eventos seguem a URL da conta.
- `paid_at` (string, nulo): Data e hora da confirmação do pagamento.
- `expires_at` (string, nulo): Data e hora limite para pagamento. `null` nas cobranças de ciclo de assinatura, que já são criadas pagas.
- `created_at` (string): Data e hora de criação.
## Status
| Status | Descrição |
|---|---|
| `pending` | Aguardando pagamento dentro do prazo. |
| `paid` | Pagamento confirmado e valor líquido creditado. |
| `expired` | Prazo encerrado sem pagamento. |
| `refunded` | Valor integral devolvido ao pagador, por devolução ou por MED. |
Uma cobrança `pending` cujo prazo já terminou é retornada como `expired`, aqui, na listagem e no filtro `status`. Devoluções parciais não alteram o status.
## Frequência de consulta
Acompanhe o pagamento pelo evento [`payment.confirmed`](/docs/eventos/payment-confirmed), enviado logo após a confirmação. Quando a consulta for necessária, use intervalos de alguns segundos somente enquanto o status for `pending` e encerre as consultas quando ele mudar. Devoluções posteriores são informadas pelo evento [`payment.refunded`](/docs/eventos/payment-refunded).
## Erros
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | API key ausente ou inválida. |
| `404` | `not_found` | Cobrança inexistente ou pertencente a outra conta. |
| `429` | | Limite de requisições excedido. |
---
# Listar cobranças
Fonte: https://botapix.com/docs/cobrancas/listar
# Listar cobranças
`GET https://botapix.com/api/v1/charges`
A listagem inclui todas as cobranças da conta, independentemente da origem. Para restringir às cobranças criadas pela integração, use `source=api`. Cada item traz um resumo da cobrança; os atributos completos estão em [Consultar cobrança](/docs/cobrancas/consultar).
```bash title="cURL"
curl "https://botapix.com/api/v1/charges?source=api&status=paid&from=2026-09-01&to=2026-09-13&limit=100" \
-H "Authorization: Bearer $BOTAPIX_API_KEY"
```
```php title="PHP"
$client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']);
$response = $client->get('charges', [
'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY')],
'query' => ['source' => 'api', 'status' => 'paid', 'from' => '2026-09-01', 'to' => '2026-09-13', 'limit' => 100],
]);
$result = json_decode($response->getBody(), true);
```
```js title="Node.js"
const response = await fetch('https://botapix.com/api/v1/charges?source=api&status=paid&from=2026-09-01&to=2026-09-13&limit=100', {
headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}` },
});
const result = await response.json();
```
```python title="Python"
import os
import requests
response = requests.get(
"https://botapix.com/api/v1/charges?source=api&status=paid&from=2026-09-01&to=2026-09-13&limit=100",
headers={"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}"},
)
result = response.json()
```
```json title="200 OK"
{
"data": [
{
"id": 1042,
"reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"external_reference": "pedido_1042",
"source": "api",
"amount": 2990,
"status": "paid",
"metadata": {"loja": "centro", "canal": "site"},
"paid_at": "2026-09-13T14:35:12+00:00",
"created_at": "2026-09-13T14:30:00+00:00"
}
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 100,
"total": 247
}
}
```
## Parâmetros de consulta
- `status` (string): Filtra pelo status: `pending`, `paid`, `expired` ou `refunded`. O filtro usa o status exibido: `pending` traz só as cobranças ainda pagáveis, e uma cobrança pendente cujo `expires_at` já passou entra em `expired`.
- `source` (string): Filtra pela origem: `api`, `subscription`, `dashboard`, `donation`, `campaign`, `product` ou `discord`.
- `external_reference` (string): Busca pelo valor completo informado na criação, sem diferenciar maiúsculas, minúsculas e acentos. Até 255 caracteres.
- `from` (date): Data inicial de criação, inclusiva, no formato `YYYY-MM-DD`.
- `to` (date): Data final de criação, inclusiva, no formato `YYYY-MM-DD`.
- `limit` (integer): Itens por página. Padrão: `20`. Valores acima de `100` são tratados como `100`.
- `page` (integer): Página. Padrão: `1`.
As datas de `from` e `to` são interpretadas no fuso horário `America/Sao_Paulo`.
## Resposta
- `data` (array): Cobranças da página, com `id`, `reference`, `external_reference`, `source`, `amount`, `status`, `metadata`, `paid_at` e `created_at`.
- `meta` (object): Paginação.
- `meta.current_page` (integer): Página retornada.
- `meta.last_page` (integer): Última página disponível.
- `meta.per_page` (integer): Itens por página.
- `meta.total` (integer): Total de cobranças que atendem aos filtros.
> **Conciliação**
>
> Para percorrer um período sem que novas cobranças desloquem as páginas, informe um intervalo já encerrado em `from` e `to`.
## Erros
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | API key ausente ou inválida. |
| `422` | | Filtro inválido. Os campos estão em `errors`. |
| `429` | | Limite de requisições excedido. |
---
# Estatísticas
Fonte: https://botapix.com/docs/cobrancas/estatisticas
# Estatísticas
`GET https://botapix.com/api/v1/charges/stats`
Agrega as cobranças criadas no período em uma única resposta, com totais e série por dia ou por mês. Indicado para painéis de faturamento, em substituição à paginação da listagem.
```bash title="cURL"
curl "https://botapix.com/api/v1/charges/stats?period=30d&group_by=day" \
-H "Authorization: Bearer $BOTAPIX_API_KEY"
```
```php title="PHP"
$client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']);
$response = $client->get('charges/stats', [
'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY')],
'query' => ['period' => '30d', 'group_by' => 'day'],
]);
$result = json_decode($response->getBody(), true);
```
```js title="Node.js"
const response = await fetch('https://botapix.com/api/v1/charges/stats?period=30d&group_by=day', {
headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}` },
});
const result = await response.json();
```
```python title="Python"
import os
import requests
response = requests.get(
"https://botapix.com/api/v1/charges/stats?period=30d&group_by=day",
headers={"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}"},
)
result = response.json()
```
```json title="200 OK"
{
"data": {
"period": "30d",
"group_by": "day",
"from": "2026-08-14T03:00:00+00:00",
"to": "2026-09-14T02:59:59+00:00",
"totals": {
"tx_count": 147,
"paid_count": 132,
"paid_amount": 184500,
"paid_net_amount": 178965,
"pending_count": 8,
"pending_amount": 12000,
"expired_count": 5,
"refunded_count": 2,
"refunded_amount": 3500
},
"timeseries": [
{
"date": "2026-08-14",
"paid_count": 4,
"paid_amount": 5600,
"pending_count": 0,
"pending_amount": 0
}
]
}
}
```
## Parâmetros de consulta
- `period` (string): Período: `7d`, `30d`, `90d`, `1y` ou `custom`. Padrão: `30d`.
- `group_by` (string): Agrupamento da série: `day` ou `month`. Padrão: `day`.
- `source` (string): Restringe a uma origem: `api`, `subscription`, `dashboard`, `donation`, `campaign`, `product` ou `discord`. Sem o parâmetro, todas as origens são consideradas.
- `from` (date): Data inicial, no formato `YYYY-MM-DD`. Obrigatório quando `period` é `custom`.
- `to` (date): Data final, inclusiva, no formato `YYYY-MM-DD`. Obrigatório quando `period` é `custom`.
Os períodos são calculados e agrupados no fuso horário `America/Sao_Paulo`. `7d`, `30d` e `90d` compreendem, respectivamente, os 7, 30 e 90 dias anteriores e o dia atual; `1y` compreende os 12 meses anteriores e o dia atual.
## Resposta
- `period` (string): Período aplicado.
- `group_by` (string): Agrupamento aplicado.
- `from` (string): Início do período, em UTC.
- `to` (string): Fim do período, em UTC.
- `totals` (object): Totais das cobranças criadas no período. Valores monetários em centavos.
- `totals.tx_count` (integer): Cobranças criadas.
- `totals.paid_count` (integer): Cobranças pagas.
- `totals.paid_amount` (integer): Soma dos valores pagos.
- `totals.paid_net_amount` (integer): Soma dos valores líquidos creditados.
- `totals.pending_count` (integer): Cobranças aguardando pagamento dentro do prazo.
- `totals.pending_amount` (integer): Soma das cobranças aguardando pagamento.
- `totals.expired_count` (integer): Cobranças com prazo encerrado sem pagamento.
- `totals.refunded_count` (integer): Cobranças devolvidas integralmente.
- `totals.refunded_amount` (integer): Soma dos valores devolvidos.
- `timeseries` (array): Um item por dia ou por mês com cobranças criadas, com `date`, `paid_count`, `paid_amount`, `pending_count` e `pending_amount`. Em `group_by=month`, `date` é o primeiro dia do mês.
## Erros
| Status | `error` | Descrição |
|---|---|---|
| `401` | `unauthorized` | API key ausente ou inválida. |
| `422` | | Parâmetros inválidos, incluindo `from` ou `to` ausentes com `period=custom`. |
| `429` | | Limite de requisições excedido. |
---
# Idempotência
Fonte: https://botapix.com/docs/cobrancas/idempotencia
# Idempotência
Uma requisição de criação pode ser concluída no BotaPix e ter a resposta perdida por falha de rede. Com o header `Idempotency-Key`, a repetição dessa requisição retorna o recurso já criado, sem gerar uma segunda cobrança para o pagador.
```http
Idempotency-Key: pedido_1042
```
O header é aceito em [`POST /charges`](/docs/cobrancas/criar) e [`POST /subscriptions`](/docs/assinaturas/criar).
## Comportamento
| Requisição | Resposta |
|---|---|
| Chave ainda não utilizada | `201 Created` com o recurso criado. |
| Chave já utilizada, mesmo corpo | `200 OK` com o recurso original. |
| Chave já utilizada, corpo diferente | `422` com `error` igual a `idempotency_key_reused`. |
| Chave com mais de 255 caracteres, fora de UTF-8 ou com caracteres de controle | `422` com `error` igual a `invalid_idempotency_key`. |
| Sem o header | Cada requisição cria um novo recurso. |
As chaves são exclusivas de cada conta e não expiram. A comparação diferencia maiúsculas, minúsculas e acentos: `Pedido-1` e `pedido-1` são chaves diferentes. Requisições simultâneas com a mesma chave produzem um único recurso. Espaços no início e no fim da chave são desconsiderados.
## Campos comparados
A comparação do corpo considera apenas os campos que definem o recurso.
| Endpoint | Campos |
|---|---|
| `POST /charges` | `amount`, `external_reference`, `description`, `expiration`, `customer`, `notification_url`, `metadata` |
| `POST /subscriptions` | `amount`, `customer.name`, `customer.document`, `description`, `external_reference`, `start_date`, `end_date` |
Campos fora da lista, como `redirect_url`, podem variar entre as tentativas. Em cobranças, `notification_url` e `metadata` só entram na comparação quando enviados, e o `metadata` é comparado como foi enviado, incluindo a ordem das chaves. Em assinaturas, `customer.document` é comparado sem máscara.
## Escolha da chave
Use um identificador estável da operação na sua aplicação, como o identificador do pedido ou da assinatura. Valores gerados a cada tentativa, como UUIDs aleatórios ou timestamps, não oferecem proteção.
Uma nova cobrança para o mesmo pedido, após a expiração da anterior, é uma nova operação e exige uma nova chave, como `pedido_1042_2`.
## Erros
```json title="422 Unprocessable Content"
{
"error": "idempotency_key_reused",
"message": "Esta Idempotency-Key já foi usada com parâmetros diferentes."
}
```
```json title="422 Unprocessable Content"
{
"error": "invalid_idempotency_key",
"message": "A Idempotency-Key deve ter no máximo 255 caracteres."
}
```
---
# Exibir o QR no seu site
Fonte: https://botapix.com/docs/cobrancas/exibir-qr
# Exibir o QR no seu site
O caminho padrão de pagamento é a página hospedada em `payment_url`: o pagador abre o link, paga o Pix e é redirecionado de volta. Quando o pagamento precisa acontecer dentro da sua interface, por exemplo numa janela do jogo ou na etapa final do checkout, use o **checkout transparente**: a resposta da cobrança também traz o QR Code e o código Pix Copia e Cola.
O checkout transparente é ativado por conta, a pedido. Sem ele, a resposta não traz o campo `pix` e o pagamento acontece no `payment_url`.
## Ativar
1. Em **Dashboard > API & Webhooks**, na aba **Checkout transparente**, selecione **Ativar checkout transparente**.
2. Informe onde o QR será exibido, como funciona o fluxo de pagamento e o volume mensal estimado.
3. A resposta chega no painel e por e-mail.
Para pedir, a conta precisa ter a identidade verificada e uma chave Pix de saque cadastrada. O checkout transparente pode ser desativado em caso de uso indevido ou de excesso de contestações (MED); depois disso, as cobranças novas voltam a usar só o `payment_url`.
## O campo `pix`
Com o checkout transparente ativo, [Criar cobrança](/docs/cobrancas/criar) e [Consultar cobrança](/docs/cobrancas/consultar) retornam o objeto `pix` enquanto a cobrança aceita pagamento (status `pending`, dentro de `expires_at`). Cobranças pagas, expiradas ou devolvidas não trazem o campo. A [listagem](/docs/cobrancas/listar) nunca traz o campo.
```json title="201 Created"
{
"data": {
"id": 1042,
"reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"amount": 2990,
"status": "pending",
"payment_url": "https://botapix.com/pagar/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe",
"pix": {
"copia_e_cola": "00020101021226850014BR.GOV.BCB.PIX2563...",
"qr_code": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i..."
},
"expires_at": "2026-10-22T15:00:00+00:00",
"created_at": "2026-10-22T14:30:00+00:00"
}
}
```
- `pix.copia_e_cola` (string): Código Pix Copia e Cola (BR Code). Exiba com um botão de copiar: no celular, o pagador cola o código no app do banco.
- `pix.qr_code` (string): Imagem do QR Code em SVG, como data URI. Pode ser usada diretamente no `src` de uma `` e mantém a nitidez em qualquer tamanho.
## Exibir na página
```html title="HTML"
Pague até .
``` ```js title="Node.js" const response = await fetch('https://botapix.com/api/v1/charges', { method: 'POST', headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': `pedido_${order.id}`, }, body: JSON.stringify({ amount: order.totalCents, external_reference: String(order.id) }), }); const { data: charge } = await response.json(); if (charge.pix) { // Checkout transparente ativo: exibe dentro da sua interface. renderPix({ qr: charge.pix.qr_code, code: charge.pix.copia_e_cola, expiresAt: charge.expires_at }); } else { // Sem checkout transparente: redireciona para a página de pagamento. redirect(charge.payment_url); } ``` > **Mantenha o payment_url como alternativa** > > O campo `payment_url` continua presente em todas as respostas. Use-o como alternativa quando o pagador estiver no mesmo aparelho e preferir abrir a página de pagamento. ## Confirmar o pagamento O QR não informa quando o pagamento acontece. Libere o pedido somente após o evento [`payment.confirmed`](/docs/eventos/payment-confirmed). Para atualizar a tela enquanto o pagador está nela, consulte a cobrança em intervalos de alguns segundos e pare ao receber `paid` ou `expired`; o webhook continua sendo a confirmação de referência. > **Prazo do QR** > > O código deixa de aceitar pagamento em `expires_at`. Mostre o prazo restante na tela e, quando ele acabar, crie uma nova cobrança em vez de reaproveitar o código anterior. --- # Criar assinatura Fonte: https://botapix.com/docs/assinaturas/criar # Criar assinatura `POST https://botapix.com/api/v1/subscriptions` A assinatura é criada com status `pending_auth` e retorna o código `authorization_pix_copia_cola`. O pagador autoriza a recorrência uma única vez, colando o código na opção Pix Copia e Cola do aplicativo do banco. A partir da data de início, o valor mensal é debitado automaticamente. Cada mudança de status gera um evento de webhook, e cada ciclo liquidado gera um `payment.confirmed` com `source` igual a `subscription`. | Etapa | Status | Evento | |---|---|---| | Assinatura criada | `pending_auth` | | | Pagador autoriza no banco | `active` | `subscription.activated` | | Pagador recusa a autorização | `rejected` | `subscription.rejected` | | Ciclo mensal liquidado | `active` | `payment.confirmed` | | Cancelamento pela API ou pelo pagador | `canceled` | `subscription.canceled` | ```bash title="cURL" curl https://botapix.com/api/v1/subscriptions \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: assinante_207" \ -d '{ "amount": 2500, "customer": { "name": "João Silva", "document": "123.456.789-09" }, "description": "Plano mensal", "external_reference": "assinante_207", "start_date": "2026-10-01" }' ``` ```php title="PHP" $client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']); $response = $client->post('subscriptions', [ 'headers' => [ 'Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY'), 'Idempotency-Key' => 'assinante_207', ], 'json' => [ 'amount' => 2500, 'customer' => ['name' => 'João Silva', 'document' => '123.456.789-09'], 'description' => 'Plano mensal', 'external_reference' => 'assinante_207', 'start_date' => '2026-10-01', ], ]); $subscription = json_decode($response->getBody(), true)['data']; ``` ```js title="Node.js" const response = await fetch('https://botapix.com/api/v1/subscriptions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'assinante_207', }, body: JSON.stringify({ amount: 2500, customer: { name: 'João Silva', document: '123.456.789-09' }, description: 'Plano mensal', external_reference: 'assinante_207', start_date: '2026-10-01', }), }); const { data: subscription } = await response.json(); ``` ```python title="Python" import os import requests response = requests.post( "https://botapix.com/api/v1/subscriptions", headers={ "Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}", "Idempotency-Key": "assinante_207", }, json={ "amount": 2500, "customer": {"name": "João Silva", "document": "123.456.789-09"}, "description": "Plano mensal", "external_reference": "assinante_207", "start_date": "2026-10-01", }, ) subscription = response.json()["data"] ``` ```json title="201 Created" { "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "status": "pending_auth", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva", "document": "12345678909" }, "authorization_pix_copia_cola": "00020101021226180014BR.GOV.BCB.PIX...6304A1B2", "start_date": "2026-10-01", "end_date": null, "current_cycle": null, "next_cycle_date": null, "approved_at": null, "canceled_at": null, "created_at": "2026-09-13T14:30:00+00:00" } } ``` ## Headers - `Authorization` (string, obrigatório): `Bearer` seguido da API key. - `Idempotency-Key` (string): Chave única da operação, com até 255 caracteres. Consulte [Idempotência](/docs/cobrancas/idempotencia). ## Corpo da requisição - `amount` (integer, obrigatório): Valor mensal em centavos. Mínimo de `1000`, máximo de `9999999999`. - `customer` (object, obrigatório): Dados do pagador titular da autorização. - `customer.name` (string, obrigatório): Nome do pagador. Até 140 caracteres. - `customer.document` (string, obrigatório): CPF ou CNPJ válido do pagador, com ou sem máscara. - `description` (string): Descrição exibida ao pagador no aplicativo do banco. Até 35 caracteres. - `external_reference` (string): Identificador do assinante na sua aplicação. Retornado nos eventos. Até 255 caracteres. - `start_date` (date): Data de início da recorrência, no formato `YYYY-MM-DD`, a partir do dia seguinte. O Pix Automático não aceita recorrência que começa no dia da criação. Padrão: dia seguinte. - `end_date` (date): Data de término, no formato `YYYY-MM-DD`, posterior a `start_date`. Sem o campo, a assinatura não tem término. ## Resposta Retorna `201 Created` com a assinatura. Uma requisição repetida com a mesma `Idempotency-Key` retorna `200 OK` com a assinatura original. Os atributos estão descritos em [Consultar assinatura](/docs/assinaturas/consultar#atributos). > **Primeiro débito** > > O débito de cada ciclo é agendado no banco do pagador com pelo menos 3 dias de antecedência. Quando a data de início fica a menos de 3 dias da autorização, o primeiro débito ocorre cerca de 3 dias após a autorização. Débitos com vencimento em fim de semana ou feriado são realizados no dia útil seguinte. Os ciclos seguintes mantêm o dia da data de início. A data agendada de cada débito é retornada em `current_cycle` ao [consultar a assinatura](/docs/assinaturas/consultar#ciclo-atual). ## Erros | Status | `error` | Descrição | |---|---|---| | `401` | `unauthorized` | API key ausente ou inválida. | | `403` | `kyc_required` | Recebimentos indisponíveis para a conta. | | `422` | | Parâmetros inválidos, incluindo CPF ou CNPJ com dígito verificador inválido. | | `422` | `idempotency_key_reused` | `Idempotency-Key` já utilizada com outro corpo. | | `422` | `invalid_idempotency_key` | `Idempotency-Key` com mais de 255 caracteres, fora de UTF-8 ou com caracteres de controle. | | `422` | `psp_rejected` | Assinatura recusada pela instituição financeira. Detalhes em `violations`. | | `429` | | Limite de requisições excedido. | | `500` | `internal_error` | Assinatura não criada. A requisição pode ser repetida com a mesma `Idempotency-Key`. | --- # Consultar e listar Fonte: https://botapix.com/docs/assinaturas/consultar # Consultar e listar assinaturas `GET https://botapix.com/api/v1/subscriptions/{id}` Retorna uma assinatura pelo `id` numérico ou pelo `reference`. Enquanto a assinatura aguarda autorização, a resposta inclui o código `authorization_pix_copia_cola`, que pode ser exibido novamente ao pagador. ```bash title="cURL" curl https://botapix.com/api/v1/subscriptions/207 \ -H "Authorization: Bearer $BOTAPIX_API_KEY" ``` ```php title="PHP" $client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']); $response = $client->get('subscriptions/207', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY')], ]); $subscription = json_decode($response->getBody(), true)['data']; ``` ```js title="Node.js" const response = await fetch('https://botapix.com/api/v1/subscriptions/207', { headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}` }, }); const { data: subscription } = await response.json(); ``` ```python title="Python" import os import requests response = requests.get( "https://botapix.com/api/v1/subscriptions/207", headers={"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}"}, ) subscription = response.json()["data"] ``` ```json title="200 OK" { "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "status": "active", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva", "document": "12345678909" }, "authorization_pix_copia_cola": null, "start_date": "2026-10-01", "end_date": null, "current_cycle": { "due_date": "2026-10-01", "debit_date": "2026-10-01", "status": "scheduled" }, "next_cycle_date": "2026-11-01", "approved_at": "2026-09-13T14:41:07+00:00", "canceled_at": null, "created_at": "2026-09-13T14:30:00+00:00" } } ``` ## Parâmetros de rota - `id` (string, obrigatório): `id` numérico ou `reference` da assinatura. ## Atributos - `id` (integer): Identificador da assinatura. - `reference` (string): Identificador da recorrência no Pix Automático. - `status` (string): Status da assinatura. Consulte [Status](#status). - `amount` (integer): Valor de cada débito, em centavos. - `periodicity` (string): Periodicidade dos débitos: `MENSAL`, `TRIMESTRAL`, `SEMESTRAL` ou `ANUAL`. Assinaturas criadas pela API são sempre `MENSAL`; os outros valores aparecem em assinaturas criadas na página pública da conta. - `customer` (object): Dados do pagador. - `customer.name` (string): Nome do pagador. - `customer.document` (string): CPF ou CNPJ do pagador, somente dígitos. - `authorization_pix_copia_cola` (string, nulo): Código de autorização. Preenchido somente no status `pending_auth`. - `start_date` (string): Data de início. - `end_date` (string, nulo): Data de término. - `current_cycle` (object, nulo): Cobrança do ciclo já enviada ao banco do pagador. `null` até a primeira ser enviada, o que acontece até 4 dias antes do vencimento. Consulte [Ciclo atual](#ciclo-atual). - `current_cycle.due_date` (string): Vencimento do ciclo. Pode ser posterior à data prevista do ciclo quando a autorização ocorre a menos de 3 dias dela. - `current_cycle.debit_date` (string, nulo): Data em que o banco do pagador agendou o débito. Quando o vencimento cai em fim de semana ou feriado, é o dia útil seguinte. `null` enquanto o débito não está agendado. - `current_cycle.status` (string): Situação da cobrança do ciclo. Consulte [Ciclo atual](#ciclo-atual). - `next_cycle_date` (string, nulo): Data prevista do próximo ciclo ainda não enviado ao banco. Preenchido somente no status `active`. - `approved_at` (string, nulo): Data e hora da autorização pelo pagador. - `canceled_at` (string, nulo): Data e hora do cancelamento. - `created_at` (string): Data e hora de criação. ## Status | Status | Descrição | Pode mudar para | |---|---|---| | `pending_auth` | Aguardando autorização do pagador. | `active`, `rejected`, `canceled` | | `active` | Autorizada. Os ciclos são debitados conforme `periodicity`. | `canceled` | | `rejected` | Autorização recusada pelo pagador ou pela instituição financeira. | | | `canceled` | Cancelada. Nenhum novo ciclo é debitado. | | ## Ciclo atual | `current_cycle.status` | Descrição | |---|---| | `processing` | Cobrança enviada ao banco do pagador, aguardando o agendamento do débito. | | `scheduled` | Débito agendado para `debit_date`. | | `paid` | Débito realizado. O valor líquido é creditado na conta e o evento [`payment.confirmed`](/docs/eventos/payment-confirmed) é enviado com `source` igual a `subscription`. | | `failed` | Débito recusado ou não realizado pelo banco do pagador. | | `canceled` | Cobrança do ciclo cancelada pelo recebedor ou pelo pagador. | A cobrança de cada ciclo é enviada ao banco do pagador com pelo menos 3 dias de antecedência do vencimento. Até lá, `next_cycle_date` indica a data prevista. ## Listar assinaturas `GET https://botapix.com/api/v1/subscriptions` Lista as assinaturas da conta, da mais recente para a mais antiga. Cada item tem os mesmos atributos da consulta. - `status` (string): Filtra pelo status: `pending_auth`, `active`, `rejected` ou `canceled`. Outro valor retorna `422`. - `limit` (integer): Itens por página. Padrão: `20`. Valores acima de `100` são tratados como `100`. - `page` (integer): Página. Padrão: `1`. ```json title="200 OK" { "data": [ { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "status": "active", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva", "document": "12345678909" }, "authorization_pix_copia_cola": null, "start_date": "2026-10-01", "end_date": null, "approved_at": "2026-09-13T14:41:07+00:00", "canceled_at": null, "created_at": "2026-09-13T14:30:00+00:00" } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 } } ``` ## Erros | Status | `error` | Descrição | |---|---|---| | `401` | `unauthorized` | API key ausente ou inválida. | | `404` | `not_found` | Assinatura inexistente ou pertencente a outra conta. | | `429` | | Limite de requisições excedido. | --- # Cancelar assinatura Fonte: https://botapix.com/docs/assinaturas/cancelar # Cancelar assinatura `DELETE https://botapix.com/api/v1/subscriptions/{id}` Cancela assinaturas com status `pending_auth` ou `active`. A autorização é encerrada no banco do pagador e nenhum novo ciclo é debitado; ciclos já liquidados permanecem no saldo. Após o cancelamento, o evento [`subscription.canceled`](/docs/webhooks/eventos#eventos-de-assinatura) é enviado. O mesmo evento é enviado quando o pagador cancela a autorização diretamente no aplicativo do banco. ```bash title="cURL" curl -X DELETE https://botapix.com/api/v1/subscriptions/207 \ -H "Authorization: Bearer $BOTAPIX_API_KEY" ``` ```php title="PHP" $client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/v1/']); $response = $client->delete('subscriptions/207', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_API_KEY')], ]); $subscription = json_decode($response->getBody(), true)['data']; ``` ```js title="Node.js" const response = await fetch('https://botapix.com/api/v1/subscriptions/207', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.BOTAPIX_API_KEY}` }, }); const { data: subscription } = await response.json(); ``` ```python title="Python" import os import requests response = requests.delete( "https://botapix.com/api/v1/subscriptions/207", headers={"Authorization": f"Bearer {os.environ['BOTAPIX_API_KEY']}"}, ) subscription = response.json()["data"] ``` ```json title="200 OK" { "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "status": "canceled", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva", "document": "12345678909" }, "authorization_pix_copia_cola": null, "start_date": "2026-10-01", "end_date": null, "current_cycle": null, "next_cycle_date": null, "approved_at": "2026-09-13T14:41:07+00:00", "canceled_at": "2026-09-20T09:00:00+00:00", "created_at": "2026-09-13T14:30:00+00:00" } } ``` ## Parâmetros de rota - `id` (string, obrigatório): `id` numérico ou `reference` da assinatura. ## Resposta Retorna `200 OK` com a assinatura no status `canceled`. Os atributos estão descritos em [Consultar assinatura](/docs/assinaturas/consultar#atributos). ## Erros | Status | `error` | Descrição | |---|---|---| | `401` | `unauthorized` | API key ausente ou inválida. | | `404` | `not_found` | Assinatura inexistente ou pertencente a outra conta. | | `422` | `invalid_state` | Assinatura já cancelada ou recusada. | | `429` | | Limite de requisições excedido. | --- # Saldo e extrato Fonte: https://botapix.com/docs/dinheiro/saldo-e-extrato # Saldo e extrato O saldo da conta tem três partes. Os valores são em centavos. | Parte | Descrição | |---|---| | `available` | Disponível para saque. Já desconta os saques em andamento. | | `on_hold` | Pagamentos confirmados ainda no prazo de liberação. | | `disputed` | Valor bloqueado por disputas (MED) abertas. Pode ser negativo quando o valor disputado já tinha sido sacado: o débito é compensado nos recebimentos seguintes. | Os dois endpoints exigem a permissão `balance:read`, presente nas chaves **Financeiro** e **Somente leitura**. Consulte [Permissões](/docs/autenticacao#permissoes). ## Consultar saldo `GET https://botapix.com/api/v1/balance` ```json title="200 OK" { "data": { "available": 125090, "on_hold": 30000, "disputed": 5000, "pending_withdrawals": 20000, "currency": "BRL", "livemode": true, "as_of": "2026-10-23T14:30:00+00:00" } } ``` - `available` (integer): Disponível para saque, em centavos. - `on_hold` (integer): Em liberação, em centavos. - `disputed` (integer): Bloqueado por disputas, em centavos. - `pending_withdrawals` (integer): Saques agendados ou em envio, em centavos. Esse valor já está fora de `available`. - `as_of` (string): Data e hora da consulta. Com chave de teste, retorna o saldo simulado do [ambiente de testes](/docs/ambientes-e-testes), com `livemode: false`. ## Listar extrato `GET https://botapix.com/api/v1/statement` Lista os lançamentos do saldo, do mais recente para o mais antigo. Cada lançamento informa quanto variou cada parte do saldo: um pagamento entra em `on_hold`; a liberação move o mesmo valor de `on_hold` para `available`. - `type` (string): Filtra por tipo. Consulte [Tipos de lançamento](#tipos-de-lancamento). - `from` (string): Data inicial, `YYYY-MM-DD`, inclusiva. - `to` (string): Data final, `YYYY-MM-DD`, inclusiva. - `before` (integer): Cursor: retorna lançamentos anteriores a este `id`. Use o `meta.next_before` da página anterior. - `limit` (integer): Itens por página. Padrão 50, máximo 100. ```json title="200 OK" { "data": [ { "id": 9821, "type": "withdrawal", "available": -2000, "on_hold": 0, "disputed": 0, "charge_id": null, "withdrawal_id": 318, "refund_id": null, "livemode": true, "created_at": "2026-10-23T14:30:00+00:00" }, { "id": 9820, "type": "release", "available": 2900, "on_hold": -2900, "disputed": 0, "charge_id": 1042, "withdrawal_id": null, "refund_id": null, "livemode": true, "created_at": "2026-10-22T03:00:00+00:00" } ], "meta": { "has_more": true, "next_before": 9820 } } ``` ### Tipos de lançamento | `type` | Efeito | |---|---| | `payment` | Pagamento confirmado: o valor líquido entra em `on_hold`. | | `release` | Fim do prazo de liberação: o valor passa de `on_hold` para `available`. | | `refund` | Devolução ao pagador: o valor sai de `available` (ou de `on_hold`, na devolução integral de um pagamento ainda em liberação). | | `refund_returned` | Devolução não realizada: o valor volta para `available`. | | `withdrawal` | Saque solicitado: o valor sai de `available`. | | `withdrawal_completed` | Saque enviado. Sem variação: o valor já tinha saído no `withdrawal`. | | `withdrawal_returned` | Saque não realizado: o valor volta para `available`. | | `dispute_hold` | Disputa aberta: o valor passa de `available` para `disputed`. | | `dispute_release` | Disputa encerrada a favor da conta: o valor volta para `available`. | | `dispute_debit` | Disputa aceita: o valor sai de `disputed` em definitivo. | | `adjustment` | Ajuste feito pelo suporte. | Para conciliar, some as variações de cada parte: o total de `available` de todos os lançamentos é o saldo disponível. --- # Saques Fonte: https://botapix.com/docs/dinheiro/saques # Saques Solicita um saque do saldo disponível para a **chave Pix cadastrada na conta**, em Dashboard → Configurações. A API não aceita chave Pix na requisição: o destino é sempre o da conta. `POST https://botapix.com/api/v1/withdrawals` Exige a permissão `withdrawals:write`, presente nas chaves **Financeiro**. Consulte [Permissões](/docs/autenticacao#permissoes). - `amount` (integer, obrigatório): Valor em centavos, debitado do saldo disponível. Mínimo de `1000`. A tarifa de saque é descontada do valor enviado. - `Idempotency-Key` (header): Mesma chave e mesmo corpo retornam o saque original com `200`, sem criar outro. Mesma regra das [cobranças](/docs/cobrancas/idempotencia). ```bash title="cURL" curl -X POST https://botapix.com/api/v1/withdrawals \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: saque-2026-10-23" \ -d '{ "amount": 20000 }' ``` ```json title="202 Accepted" { "data": { "id": 318, "status": "scheduled", "livemode": true, "amount": 20000, "fee": 300, "net_amount": 19700, "destination": { "type": "email", "key": "jo***@exemplo.com" }, "process_after": "2026-10-23T20:30:00+00:00", "completed_at": null, "failed_at": null, "canceled_at": null, "created_at": "2026-10-23T14:30:00+00:00" } } ``` O valor sai do saldo disponível no pedido. O Pix é enviado a partir de `process_after`. Saques acima do limite de aprovação automática ficam com status `pending_approval` até a análise, e então seguem o mesmo fluxo. ## Status | `status` | Descrição | |---|---| | `pending_approval` | Aguardando análise. | | `scheduled` | Aprovado, com envio a partir de `process_after`. | | `pending` | Na fila de envio. | | `processing` | Pix em envio. | | `completed` | Pix enviado. | | `failed` | Não realizado. O valor volta para o saldo disponível. | | `canceled` | Cancelado antes do envio. O valor volta para o saldo disponível. | As mudanças de status geram os eventos [`withdrawal.scheduled`](/docs/eventos/withdrawal-scheduled), [`withdrawal.completed`](/docs/eventos/withdrawal-completed), [`withdrawal.failed`](/docs/eventos/withdrawal-failed) e [`withdrawal.canceled`](/docs/eventos/withdrawal-canceled), para saques pedidos pela API ou pelo dashboard. ## Listar e consultar `GET https://botapix.com/api/v1/withdrawals` Lista os saques da conta, do mais recente para o mais antigo. Aceita `status`, `limit` (padrão 20, máximo 100) e `page`. A consulta de um saque é `GET /api/v1/withdrawals/{id}`. Os dois exigem `withdrawals:read`. ## Erros | Status | `error` | Descrição | |---|---|---| | `403` | `account_suspended` | Conta suspensa. | | `403` | `kyc_required` | Saques indisponíveis para a conta. | | `403` | `test_mode_unsupported` | Chave de teste: saques não têm ambiente de testes. | | `409` | `pix_key_missing` | A conta não tem chave Pix cadastrada. | | `409` | `pix_key_invalid` | A chave Pix cadastrada não é válida. Confira em Dashboard → Configurações. | | `422` | `insufficient_balance` | Saldo disponível menor que `amount`. A resposta traz `available`, em centavos. | | `422` | `amount_too_low_for_fee` | O valor enviado seria zero depois da tarifa. | | `429` | | Mais de 10 saques na última hora. | --- # Devoluções Fonte: https://botapix.com/docs/dinheiro/devolucoes # Devoluções O Pix de devolução vai para a conta que pagou a cobrança. O valor sai do **saldo disponível** da conta no momento do pedido. `POST https://botapix.com/api/v1/charges/{id}/refunds` Exige a permissão `refunds:write`, presente nas chaves **Financeiro**. Consulte [Permissões](/docs/autenticacao#permissoes). - `id` (string, obrigatório): Identificador numérico ou `reference` da cobrança. - `amount` (integer): Valor em centavos. Sem `amount`, devolve tudo o que ainda pode ser devolvido. - `reason` (string): Motivo da devolução, até 140 caracteres. - `Idempotency-Key` (header): Mesma chave e mesmo corpo retornam a devolução original com `200`, sem criar outra. Mesma regra das [cobranças](/docs/cobrancas/idempotencia). ```bash title="cURL" curl -X POST https://botapix.com/api/v1/charges/1042/refunds \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: devolucao-pedido-1042" \ -d '{ "amount": 2990, "reason": "Pedido cancelado" }' ``` ```json title="201 Created" { "data": { "id": 91, "charge_id": 1042, "status": "processing", "livemode": true, "amount": 2990, "reason": "Pedido cancelado", "created_at": "2026-10-23T14:30:00+00:00", "completed_at": null, "failed_at": null, "failure_reason": null } } ``` A devolução também pode ser feita no recibo do pagamento, em Dashboard → Pagamentos. A devolução costuma se concluir em segundos. O resultado chega pelos eventos [`refund.completed`](/docs/eventos/refund-completed) e [`refund.failed`](/docs/eventos/refund-failed). ## Valores - Devoluções até 30 dias depois do pagamento. - Uma cobrança aceita várias devoluções parciais, até o valor pago. - A tarifa da cobrança não é devolvida: devolver uma cobrança de R$ 29,90 debita R$ 29,90 do saldo disponível. - Se o saldo disponível não cobre o valor, a devolução não é criada e a resposta é `422` com `insufficient_balance`. - Uma devolução não realizada volta para o saldo disponível. Quando as devoluções somam o valor pago, a cobrança passa para `refunded` e o evento [`payment.refunded`](/docs/eventos/payment-refunded) é enviado. ## Status | `status` | Descrição | |---|---| | `processing` | Pix de devolução em envio. | | `completed` | Valor devolvido ao pagador. | | `failed` | Não realizada. O valor volta para o saldo disponível. | ## Listar devoluções `GET https://botapix.com/api/v1/charges/{id}/refunds` Lista as devoluções de uma cobrança, da mais recente para a mais antiga. Exige `charges:read`. ## No extrato A devolução aparece no [extrato](/docs/dinheiro/saldo-e-extrato) como `refund`, com `refund_id`. Uma devolução não realizada gera um lançamento `refund_returned`, que devolve o valor ao saldo disponível. ## Ambiente de testes Com uma chave de teste, a devolução é simulada na hora e retorna `completed`, com `id` nulo e `livemode: false`. A `Idempotency-Key` funciona como na produção. O saldo de produção não é alterado. ## Erros | Status | `error` | Descrição | |---|---|---| | `403` | `account_suspended` | Conta suspensa. | | `403` | `kyc_required` | Conta em verificação de identidade. | | `404` | `not_found` | Cobrança inexistente ou de outra conta. | | `409` | `invalid_state` | A cobrança não está paga. | | `409` | `already_refunded` | A cobrança já foi devolvida integralmente. | | `409` | `dispute_open` | A cobrança tem uma disputa (MED) aberta. | | `409` | `refund_not_available` | O pagamento não pode ser devolvido pela API. | | `422` | `refund_not_supported` | Ciclos de assinatura não são devolvidos pela API. | | `422` | `refund_window_expired` | Pagamento feito há mais de 30 dias. | | `422` | `invalid_amount` | Valor acima do que ainda pode ser devolvido. A resposta traz `refundable`, em centavos. | | `422` | `insufficient_balance` | Saldo disponível menor que o valor. A resposta traz `available`, em centavos. | --- # Disputas (MED) Fonte: https://botapix.com/docs/dinheiro/disputas # Disputas (MED) O MED (Mecanismo Especial de Devolução) do Banco Central permite que o banco do pagador conteste um Pix, em casos de suspeita de fraude. Enquanto a disputa está aberta, o valor contestado fica bloqueado no saldo em `disputed` e não pode ser sacado. `GET https://botapix.com/api/v1/disputes` Lista as disputas dos pagamentos da conta, da mais recente para a mais antiga. Exige a permissão `disputes:read`, presente nas chaves **Somente leitura** e **Financeiro**. Consulte [Permissões](/docs/autenticacao#permissoes). - `status` (string): Filtra por status. Consulte [Status](#status). - `charge_id` (integer): Somente as disputas de uma cobrança. - `limit` (integer): Itens por página. Padrão 20, máximo 100. - `page` (integer): Página. ```bash title="cURL" curl https://botapix.com/api/v1/disputes?status=open \ -H "Authorization: Bearer $BOTAPIX_API_KEY" ``` ```json title="200 OK" { "data": [ { "id": 57, "charge_id": 1042, "status": "open", "livemode": true, "amount": 2990, "reason": "scam", "opened_at": "2026-10-23T14:30:00+00:00", "analysis_due_at": "2026-10-30T14:30:00+00:00", "closed_at": null } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 } } ``` A consulta de uma disputa é `GET /api/v1/disputes/{id}`. ## Atributos - `charge_id` (integer): Cobrança contestada. - `amount` (integer): Valor contestado, em centavos. - `reason` (string): Situação informada pelo banco do pagador: `scam` (golpe), `account_takeover` (conta tomada), `coercion` (coação), `fraudulent_access` (acesso fraudulento), `other` ou `unknown`. - `analysis_due_at` (string): Prazo para a conclusão da análise. - `closed_at` (string): Data do encerramento. `null` enquanto a disputa está aberta. ## Status | `status` | Descrição | Valor | |---|---|---| | `open` | Disputa aberta. | Bloqueado em `disputed`. | | `under_review` | Em análise, com as informações da transação já enviadas. | Bloqueado em `disputed`. | | `won` | Encerrada a favor da conta. | Volta para o saldo disponível. | | `canceled` | Cancelada pelo banco do pagador. | Volta para o saldo disponível. | | `lost` | Encerrada a favor do pagador. | Devolvido ao pagador. | Cada mudança gera um evento: [`dispute.opened`](/docs/eventos/dispute-opened), [`dispute.updated`](/docs/eventos/dispute-updated) e [`dispute.closed`](/docs/eventos/dispute-closed). Uma disputa `lost` também gera [`payment.refunded`](/docs/eventos/payment-refunded) quando o valor integral é devolvido. ## Como responder Se a transação é legítima, envie as informações que a comprovam (o que foi vendido, comprovante de entrega, conversas com o pagador) por um chamado em **Dashboard → Suporte**, antes de `analysis_due_at`. As informações são encaminhadas à análise da disputa. ## No saldo e no extrato O bloqueio aparece no [extrato](/docs/dinheiro/saldo-e-extrato) como `dispute_hold`; o encerramento, como `dispute_release` (valor liberado) ou `dispute_debit` (valor devolvido). Uma cobrança com disputa aberta não aceita [devolução](/docs/dinheiro/devolucoes). ## Ambiente de testes Disputas não têm ambiente de testes. Com chave de teste, a resposta é `403` com `test_mode_unsupported`. --- # Catálogo de produtos Fonte: https://botapix.com/docs/produtos/catalogo # Catálogo de produtos Um produto define o preço, o estoque e o que o comprador recebe quando o Pix é confirmado. Cada produto tem um link de compra hospedado (`url`) e pode ser vendido pela API com [`POST /charges`](/docs/produtos/vender). Os endpoints de produtos exigem as permissões `products:read` e `products:write`, presentes nas chaves **Loja**, e funcionam somente com chave de produção. Consulte [Permissões](/docs/autenticacao#permissoes). ## Identificação da loja Criar e alterar produtos exige que a conta tenha a loja identificada: um nome e ao menos um contato para o comprador (e-mail, WhatsApp, Discord ou Telegram), além das regras de venda aceitas. As duas etapas são feitas uma única vez, em **Produtos**, no painel. O nome e os contatos aparecem no link de compra e na página da entrega. Enquanto faltar uma delas, `POST /products` e `PATCH /products/{id}` retornam `422` com `store_identification_required` ou `seller_terms_required`. Consultar produtos, adicionar chaves, remover produtos e vender produtos que já existem não dependem dessa etapa. ```json title="422 Unprocessable Content" { "error": "store_identification_required", "message": "Identifique a sua loja (nome e um contato para o comprador) em Produtos, no painel do BotaPix, antes de criar, editar ou ativar produtos." } ``` ## Entrega | `delivery.type` | O comprador recebe | |---|---| | `none` | Somente a confirmação do pagamento. | | `text` | O texto de `delivery.text`, como instruções de acesso ou um código fixo. | | `link` | O link de `delivery.url`. | | `license_keys` | Uma chave de licença por unidade, retirada do estoque de chaves do produto. O `delivery.text`, se houver, acompanha as chaves. | A entrega aparece na página de pagamento logo após a confirmação e, quando a cobrança tem `customer.email`, também é enviada por e-mail. O conteúdo entregue é registrado no momento da venda: alterar o produto depois não muda entregas anteriores. ## Estoque | `stock.mode` | Comportamento | |---|---| | `unlimited` | Sem limite de unidades. | | `count` | Até `stock.count` unidades. Cada venda paga desconta a quantidade. | | `keys` | Definido automaticamente em `license_keys`: o estoque são as chaves disponíveis. | Uma cobrança pendente reserva as unidades até `expires_at`. Se o prazo vence sem pagamento, as unidades voltam ao estoque. `stock.available` já desconta as reservas. ## Criar produto `POST https://botapix.com/api/v1/products` - `name` (string, obrigatório): Nome do produto, exibido no link de compra e na entrega. Até 80 caracteres. - `description` (string): Descrição exibida no link de compra. Até 2000 caracteres. - `price` (integer, obrigatório): Preço unitário em centavos, de `100` a `10000000`. - `active` (boolean): Produto inativo não é vendido, nem pelo link nem pela API. Padrão: `true`. - `max_per_order` (integer): Unidades por compra, de `1` a `100`. Padrão: `1`. - `delivery` (object, obrigatório): O que o comprador recebe. - `delivery.type` (string, obrigatório): `none`, `text`, `link` ou `license_keys`. - `delivery.text` (string): Texto entregue. Obrigatório em `text`. Até 5000 caracteres. - `delivery.url` (string): Link `http` ou `https` entregue. Obrigatório em `link`. Até 2000 caracteres. - `stock` (object): Controle de estoque. Ignorado em `license_keys`. - `stock.mode` (string): `unlimited` ou `count`. Padrão: `unlimited`. - `stock.count` (integer): Unidades em estoque. Obrigatório em `count`. ```bash title="cURL" curl -X POST https://botapix.com/api/v1/products \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Licença anual", "price": 14990, "max_per_order": 5, "delivery": { "type": "license_keys", "text": "Ative em Configurações > Licença." } }' ``` ```json title="201 Created" { "data": { "id": "prod_8k2m4q7x1z9c3v5b", "name": "Licença anual", "description": null, "price": 14990, "active": true, "suspended": false, "url": "https://botapix.com/l/licenca-anual-a1b2c3", "image_url": null, "max_per_order": 5, "delivery": { "type": "license_keys", "text": "Ative em Configurações > Licença.", "url": null }, "stock": { "mode": "keys", "count": null, "available": 0, "keys": { "available": 0, "reserved": 0, "delivered": 0 } }, "created_at": "2026-10-23T14:30:00+00:00", "updated_at": "2026-10-23T14:30:00+00:00" } } ``` O `id` (`prod_...`) é o `product_id` usado na venda. Cada conta pode ter até 200 produtos. O atributo `suspended` indica que o BotaPix suspendeu o produto por violar as [regras de venda](https://botapix.com/termos#venda-de-produtos). Um produto suspenso não é vendido pelo link nem pela API, mesmo com `active` em `true`, e a conta é avisada do motivo por e-mail. ## Adicionar chaves `POST https://botapix.com/api/v1/products/{id}/keys` Abastece o estoque de um produto `license_keys`. Chaves repetidas na lista ou já cadastradas no produto são ignoradas. - `keys` (array, obrigatório): De 1 a 1000 chaves por requisição, uma por item, com até 500 caracteres e sem quebra de linha. ```bash title="cURL" curl -X POST https://botapix.com/api/v1/products/prod_8k2m4q7x1z9c3v5b/keys \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "keys": ["AAAA-BBBB-CCCC-0001", "AAAA-BBBB-CCCC-0002"] }' ``` ```json title="200 OK" { "data": { "added": 2, "duplicates": 0, "available": 2 } } ``` As chaves são armazenadas criptografadas e nunca são listadas pela API. Uma chave aparece somente na [entrega](/docs/produtos/vender#consultar-a-entrega) da venda que a recebeu. ## Consultar, alterar e remover `GET https://botapix.com/api/v1/products` Lista os produtos da conta, do mais recente para o mais antigo. Aceita `active`, `limit` (padrão 20, máximo 100) e `page`. A consulta de um produto é `GET /api/v1/products/{id}`. `PATCH https://botapix.com/api/v1/products/{id}` Altera somente os campos enviados, com as mesmas regras da criação. O produto resultante é validado inteiro: mudar `delivery.type` para `text` exige `delivery.text`, por exemplo. Um novo preço vale para as cobranças criadas depois da alteração. `DELETE https://botapix.com/api/v1/products/{id}` Remove o produto do catálogo, e o link de compra deixa de vender. Uma cobrança pendente deste produto ainda é entregue se for paga, e as entregas anteriores continuam disponíveis. ## Erros | Status | `error` | Descrição | |---|---|---| | `403` | `insufficient_scope` | A chave não tem `products:read` ou `products:write`. | | `403` | `test_mode_unsupported` | Chave de teste: produtos não têm ambiente de testes. | | `404` | `not_found` | Produto não encontrado na conta. | | `409` | `keys_not_supported` | Chaves enviadas para um produto que não é `license_keys`. | | `422` | | Parâmetros inválidos. Os campos estão em `errors`. | | `422` | `product_limit_reached` | A conta já tem 200 produtos. | | `422` | `store_identification_required` | A loja não tem nome e contato para o comprador. Consulte [Identificação da loja](#identificacao-da-loja). | | `422` | `seller_terms_required` | As regras de venda ainda não foram aceitas no painel. | --- # Vender um produto Fonte: https://botapix.com/docs/produtos/vender # Vender um produto A venda é uma cobrança criada com [`POST /charges`](/docs/cobrancas/criar) e `product_id`. O valor vem do preço do produto, as unidades ficam reservadas até o prazo da cobrança e a entrega acontece na confirmação do Pix. `POST https://botapix.com/api/v1/charges` Exige `charges:write` e chave de produção. - `product_id` (string, obrigatório): O `id` do produto (`prod_...`). - `quantity` (integer): Unidades, de `1` até o `max_per_order` do produto. Padrão: `1`. - `amount` (integer): Opcional. Quando enviado, deve ser igual ao preço vezes `quantity`; caso contrário, a cobrança não é criada e a resposta traz `expected_amount`. - `customer.email` (string): E-mail que recebe a entrega. Sem ele, a entrega fica na página de pagamento e na API. Os demais campos da cobrança, como `external_reference`, `expiration`, `notification_url`, `metadata` e a `Idempotency-Key`, funcionam como em [Criar cobrança](/docs/cobrancas/criar). O `description`, quando enviado, substitui o nome do produto na mensagem do Pix. ```bash title="cURL" curl -X POST https://botapix.com/api/v1/charges \ -H "Authorization: Bearer $BOTAPIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido_1042" \ -d '{ "product_id": "prod_8k2m4q7x1z9c3v5b", "quantity": 1, "external_reference": "pedido_1042", "customer": { "email": "cliente@exemplo.com" } }' ``` ```json title="201 Created" { "data": { "id": 1042, "reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe", "livemode": true, "amount": 14990, "status": "pending", "payment_url": "https://botapix.com/pagar/k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe", "expires_at": "2026-10-23T15:30:00+00:00", "created_at": "2026-10-23T14:30:00+00:00" } } ``` A cobrança aparece em [Consultar cobrança](/docs/cobrancas/consultar) e nos eventos `payment.*` com o atributo `product` (`id` e `quantity`). A `Idempotency-Key` repetida devolve a cobrança original mesmo que o preço do produto tenha mudado nesse intervalo. ## Consultar a entrega `GET https://botapix.com/api/v1/charges/{id}/delivery` O que o comprador recebeu, com as chaves. Exige `products:read`. Disponível depois que a cobrança é paga. ```json title="200 OK" { "data": { "charge_id": 1042, "product_id": "prod_8k2m4q7x1z9c3v5b", "product_name": "Licença anual", "quantity": 1, "status": "delivered", "missing": 0, "url": "https://botapix.com/entrega/Xq3...", "buyer_email": "cliente@exemplo.com", "emailed_at": "2026-10-23T14:31:02+00:00", "delivered_at": "2026-10-23T14:31:01+00:00", "created_at": "2026-10-23T14:31:01+00:00", "content": { "type": "license_keys", "text": "Ative em Configurações > Licença.", "url": null, "keys": ["AAAA-BBBB-CCCC-0001"] } } } ``` - `status` (string): `delivered` ou `failed`. Em `failed`, faltaram chaves no estoque e `missing` informa quantas. - `url` (string): Página de entrega do comprador. É o mesmo link exibido na página de pagamento e enviado por e-mail. - `content` (object): O conteúdo registrado no momento da entrega: `text`, `url` e, em `license_keys`, as chaves em `keys`. A entrega é anunciada pelos eventos [`delivery.completed`](/docs/eventos/delivery-completed) e [`delivery.failed`](/docs/eventos/delivery-failed). Os eventos não trazem o conteúdo: chaves e links ficam fora dos webhooks e são lidos neste endpoint. > **Entrega incompleta** > > Quando uma reserva vence e as chaves vão para outra venda antes de o Pix ser confirmado, a entrega sai incompleta. Reponha as chaves e envie as que faltaram ao comprador, ou [devolva o pagamento](/docs/dinheiro/devolucoes). ## Erros | Status | `error` | Descrição | |---|---|---| | `403` | `test_mode_unsupported` | `product_id` com chave de teste. | | `404` | `product_not_found` | `product_id` não encontrado na conta. | | `404` | `delivery_not_found` | A cobrança não é a venda de um produto ou ainda não foi paga. | | `409` | `product_unavailable` | Produto inativo ou suspenso. | | `409` | `out_of_stock` | Estoque insuficiente. A resposta traz `available`. | | `422` | `amount_mismatch` | `amount` diferente do preço vezes `quantity`. A resposta traz `expected_amount`. | | `422` | `invalid_quantity` | `quantity` acima do `max_per_order` do produto. | --- # Visão geral Fonte: https://botapix.com/docs/webhooks/visao-geral # Webhooks Webhooks notificam a sua aplicação, em tempo real, sobre eventos da conta. Cada evento é enviado como uma requisição `POST` para os endpoints cadastrados em [Dashboard → API](/dashboard/api), até 5 por ambiente, cada um com os eventos que escolher, ou para a [URL da própria cobrança](/docs/webhooks/configurar#url-por-cobranca). Todos são assinados com o secret do ambiente (produção ou teste). ## Eventos | Evento | Enviado quando | |---|---| | [`payment.confirmed`](/docs/eventos/payment-confirmed) | Um pagamento é confirmado e o valor líquido é creditado. | | [`payment.refunded`](/docs/eventos/payment-refunded) | Um pagamento é devolvido integralmente ao pagador. | | [`payment.expired`](/docs/eventos/payment-expired) | Uma cobrança vence sem ser paga. | | [`subscription.activated`](/docs/eventos/subscription-activated) | O pagador autoriza uma assinatura. | | [`subscription.rejected`](/docs/eventos/subscription-rejected) | A autorização de uma assinatura é recusada. | | [`subscription.canceled`](/docs/eventos/subscription-canceled) | Uma assinatura é cancelada. | | [`withdrawal.scheduled`](/docs/eventos/withdrawal-scheduled) | Um saque ganha data de envio. | | [`withdrawal.completed`](/docs/eventos/withdrawal-completed) | O Pix de um saque é enviado. | | [`withdrawal.failed`](/docs/eventos/withdrawal-failed) | Um saque não é realizado. | | [`withdrawal.canceled`](/docs/eventos/withdrawal-canceled) | Um saque é cancelado antes do envio. | | [`refund.completed`](/docs/eventos/refund-completed) | Uma devolução é concluída. | | [`refund.failed`](/docs/eventos/refund-failed) | Uma devolução não é realizada. | | [`dispute.opened`](/docs/eventos/dispute-opened) | Uma disputa (MED) é aberta e o valor é bloqueado. | | [`dispute.updated`](/docs/eventos/dispute-updated) | Uma disputa passa para análise. | | [`dispute.closed`](/docs/eventos/dispute-closed) | Uma disputa é encerrada. | | [`delivery.completed`](/docs/eventos/delivery-completed) | A venda de um produto é entregue. | | [`delivery.failed`](/docs/eventos/delivery-failed) | A venda de um produto é paga sem chaves suficientes no estoque. | | [`webhook.test`](/docs/eventos/webhook-test) | Um evento de teste é enviado pelo dashboard. | Os eventos abrangem todas as cobranças da conta, incluindo as que não foram criadas pela API. O atributo `data.source` identifica a origem de cada pagamento. ## Entrega | Característica | Comportamento | |---|---| | Requisição | `POST` com corpo JSON. | | Destinos | Uma cópia para cada endpoint ativo que assina o evento, com o mesmo `event_id` e retentativas independentes. | | Autenticidade | HMAC-SHA256 do corpo no header `X-BotaPix-Signature`. Consulte [Verificação HMAC](/docs/webhooks/assinatura-hmac). | | Confirmação | Resposta `2xx` em até 10 segundos. Redirecionamentos não são seguidos. | | Retentativas | Até 8 tentativas em cerca de 33 horas. Consulte [Retentativas](/docs/webhooks/retry-policy). | | Desligamento | Endpoint com 50 falhas seguidas é desativado até ser reativado no dashboard. | | Duplicidade | Um evento pode ser entregue mais de uma vez, sempre com o mesmo `event_id`. | | Ordem | Não garantida. Use o `status` do objeto como referência. | ## Requisitos do endpoint 1. Verificar a assinatura antes de processar o evento. 2. Descartar eventos já processados, identificados pelo `event_id`. 3. Responder `2xx` em até 10 segundos e executar o processamento em segundo plano. 4. Responder `200` a tipos de evento não tratados. Novos eventos podem ser adicionados. A configuração e um exemplo de endpoint estão em [Configurar webhooks](/docs/webhooks/configurar). --- # Configurar Fonte: https://botapix.com/docs/webhooks/configurar # Configurar webhooks ## 1. Gere o secret de assinatura Em [Dashboard → API](/dashboard/api), na aba **Webhooks**, use **Gerar secret** e confirme com a senha da conta. O valor começa com `whsec_` (`whsec_test_` no [ambiente de testes](/docs/ambientes-e-testes)) e é exibido completo uma única vez. Armazene-o como variável de ambiente no servidor que recebe os eventos. Cada ambiente tem o próprio secret: o de produção assina os eventos de todos os endpoints de produção e os da [URL por cobrança](#url-por-cobranca); o de teste, os eventos de teste. Sem o secret do ambiente, nenhum evento dele é enviado. ## 2. Cadastre os endpoints Use **Novo endpoint** e informe a URL. A conta aceita até 5 endpoints em cada ambiente, e cada URL deve atender aos requisitos: - protocolo HTTPS; - porta 443 ou 8443; - domínio ou IP público, fora de redes privadas, loopback e link-local; - resposta direta, sem redirecionamento. O endereço é validado no cadastro e novamente a cada entrega. Cada endpoint recebe uma cópia de cada evento que assina, com o mesmo `event_id` e uma fila de [retentativas](/docs/webhooks/retry-policy) própria: um endpoint fora do ar não atrasa os demais. ### Eventos de cada endpoint Por padrão, o endpoint recebe **todos os eventos**, inclusive os que forem criados depois. Para receber só alguns, desligue **Todos os eventos** e marque os desejados, por exemplo apenas `payment.confirmed` no servidor da loja e `payment.refunded` no sistema financeiro. O evento de teste é enviado a qualquer endpoint, independentemente da seleção. ### Desligamento automático Um endpoint que acumula 50 tentativas de entrega com falha seguidas é desativado, e a conta recebe um aviso no painel e por e-mail. Os eventos seguintes não são enviados a ele. Corrija o servidor e use **Reativar**: a contagem recomeça do zero. Para recuperar os eventos do período, use [Listar cobranças](/docs/cobrancas/listar). ## 3. Envie um evento de teste Use **Enviar teste** no endpoint. O BotaPix envia o evento [`webhook.test`](/docs/eventos/webhook-test) assinado somente para aquele endpoint e exibe o status retornado e o tempo de resposta. O evento de teste tem uma única tentativa e não conta para o desligamento automático. Para testar um endpoint em execução local, consulte [Testar localmente](/docs/webhooks/testar-localmente). ## Log de entregas A seção **Entregas**, na aba Webhooks, lista cada evento enviado nos últimos 90 dias, com destino, status, número de tentativas, código HTTP e tempo de resposta. É possível filtrar por endpoint, status e evento. Ao abrir uma entrega, o painel mostra o corpo enviado, os headers, os primeiros 2 KB da resposta do servidor e a explicação da falha, quando houver. Uma entrega ainda não confirmada pode ser reenviada com **Reenviar agora**: o reenvio usa o mesmo `event_id` e conta como uma tentativa a mais. Entregas confirmadas não podem ser reenviadas. ## Troca do secret A troca acontece em duas etapas, para que o servidor não recuse eventos durante a mudança: 1. Use **Trocar secret**. O novo secret é exibido uma vez e fica pendente: os eventos continuam assinados com o atual. 2. Configure o servidor para aceitar os dois secrets (veja [Verificação HMAC](/docs/webhooks/assinatura-hmac#troca-do-secret)). 3. Use **Ativar novo secret**. A partir desse momento, inclusive nas retentativas, os eventos são assinados com o novo. 4. Remova o secret antigo do servidor. Enquanto a troca estiver pendente, **Desistir da troca** descarta o novo secret. ## URL por cobrança Quando mais de um sistema usa a mesma conta, como unidades, lojas ou caixas diferentes, informe `notification_url` em [Criar cobrança](/docs/cobrancas/criar). Os eventos de pagamento dessa cobrança (`payment.confirmed`, `payment.refunded` e `payment.expired`) vão somente para essa URL, no lugar dos endpoints da conta. - A URL segue os mesmos requisitos dos endpoints e é validada novamente a cada entrega. - A assinatura usa o secret do ambiente da cobrança. Sem esse secret gerado, a criação da cobrança retorna `422` com `webhook_secret_required`. - Endpoints cadastrados não são obrigatórios para usar `notification_url`. Eles continuam recebendo os eventos das demais cobranças e das assinaturas. - Para identificar a origem no seu sistema, envie também `metadata`, retornado em `data.metadata` no evento. ## Exemplo de endpoint O exemplo abaixo verifica a assinatura, descarta eventos repetidos e enfileira o processamento. O registro do `event_id` e o enfileiramento ocorrem na mesma transação: se o enfileiramento falhar, o registro é desfeito e a retentativa seguinte é processada. ```php title="PHP" PDO::ERRMODE_EXCEPTION]); $pdo->beginTransaction(); try { $insert = $pdo->prepare('INSERT IGNORE INTO webhook_events (event_id, received_at) VALUES (?, NOW())'); $insert->execute([$event['event_id']]); if ($insert->rowCount() === 1) { match ($event['event']) { 'payment.confirmed' => enqueue($pdo, 'fulfill_order', $event['data']), 'payment.refunded' => enqueue($pdo, 'reverse_order', $event['data']), 'payment.expired' => enqueue($pdo, 'release_stock', $event['data']), 'subscription.activated', 'subscription.rejected', 'subscription.canceled' => enqueue($pdo, 'sync_subscription', $event['data']), default => null, }; } $pdo->commit(); } catch (Throwable $e) { $pdo->rollBack(); http_response_code(500); exit; } http_response_code(200); ``` A tabela `webhook_events` precisa de uma chave única em `event_id`. Mantenha os registros por pelo menos 3 dias, período superior ao das [retentativas](/docs/webhooks/retry-policy). A função `enqueue` representa a fila da aplicação e grava na mesma conexão. Exemplos de verificação em Node.js e Python estão em [Verificação HMAC](/docs/webhooks/assinatura-hmac). --- # Eventos Fonte: https://botapix.com/docs/webhooks/eventos # Eventos Todos os eventos compartilham o mesmo envelope. O objeto em `data` varia conforme o tipo do evento. - `event` (string): Tipo do evento. - `event_id` (string): Identificador único do evento, mantido em todas as tentativas de entrega e igual em todos os endpoints. - `livemode` (boolean): `true` para eventos de produção e `false` para eventos do ambiente de testes. - `data` (object): Objeto do evento. - `timestamp` (string): Data e hora de criação do evento, mantida em todas as tentativas de entrega. Novos atributos podem ser adicionados a `data`. A aplicação deve ignorar atributos desconhecidos. ## Lista de eventos | Evento | Enviado quando | `data` | |---|---|---| | [`payment.confirmed`](/docs/eventos/payment-confirmed) | Um pagamento é confirmado e o valor líquido é creditado. | Cobrança | | [`payment.refunded`](/docs/eventos/payment-refunded) | Um pagamento é devolvido integralmente ao pagador. | Cobrança | | [`payment.expired`](/docs/eventos/payment-expired) | Uma cobrança vence sem ser paga. | Cobrança | | [`subscription.activated`](/docs/eventos/subscription-activated) | O pagador autoriza uma assinatura. | Assinatura | | [`subscription.rejected`](/docs/eventos/subscription-rejected) | A autorização de uma assinatura é recusada. | Assinatura | | [`subscription.canceled`](/docs/eventos/subscription-canceled) | Uma assinatura é cancelada. | Assinatura | | [`withdrawal.scheduled`](/docs/eventos/withdrawal-scheduled) | Um saque ganha data de envio. | Saque | | [`withdrawal.completed`](/docs/eventos/withdrawal-completed) | O Pix de um saque é enviado. | Saque | | [`withdrawal.failed`](/docs/eventos/withdrawal-failed) | Um saque não é realizado. | Saque | | [`withdrawal.canceled`](/docs/eventos/withdrawal-canceled) | Um saque é cancelado antes do envio. | Saque | | [`refund.completed`](/docs/eventos/refund-completed) | Uma devolução é concluída. | Devolução | | [`refund.failed`](/docs/eventos/refund-failed) | Uma devolução não é realizada. | Devolução | | [`dispute.opened`](/docs/eventos/dispute-opened) | Uma disputa (MED) é aberta e o valor é bloqueado. | Disputa | | [`dispute.updated`](/docs/eventos/dispute-updated) | Uma disputa passa para análise. | Disputa | | [`dispute.closed`](/docs/eventos/dispute-closed) | Uma disputa é encerrada. | Disputa | | [`delivery.completed`](/docs/eventos/delivery-completed) | A venda de um produto é entregue. | Entrega | | [`delivery.failed`](/docs/eventos/delivery-failed) | A venda de um produto é paga sem chaves suficientes no estoque. | Entrega | | [`webhook.test`](/docs/eventos/webhook-test) | Um evento de teste é enviado pelo dashboard. | Mensagem | Cada endpoint escolhe os eventos que recebe. Consulte [Configurar webhooks](/docs/webhooks/configurar#eventos-de-cada-endpoint). ## Eventos de assinatura As assinaturas geram `subscription.activated`, `subscription.rejected` e `subscription.canceled` a cada mudança de status, todos com a mesma estrutura em `data`. Cada débito mensal de uma assinatura ativa gera um `payment.confirmed` com `source: subscription` e o `subscription_id`. ## Origem do pagamento | `source` | Origem | |---|---| | `api` | Cobrança criada por `POST /charges`. | | `subscription` | Ciclo de uma assinatura. | | `dashboard` | Link de pagamento criado no dashboard. | | `donation` | Doação pela página pública da conta. | | `campaign` | Contribuição para uma vaquinha. | | `product` | Compra pelo link de um [produto](/docs/produtos/catalogo). A venda de produto criada pela API tem `source` igual a `api` e o atributo `product`. | | `discord` | Compra pelo botão da loja no Discord. | Os mesmos valores são aceitos como filtro em [Listar cobranças](/docs/cobrancas/listar) e [Estatísticas](/docs/cobrancas/estatisticas). ## Eventos não tratados Responda `200` a qualquer tipo de evento que a aplicação não processe. Respostas de erro fazem o evento ser reenviado conforme a [política de retentativas](/docs/webhooks/retry-policy). --- # Verificação HMAC Fonte: https://botapix.com/docs/webhooks/assinatura-hmac # Verificação HMAC Cada evento é assinado com o secret de assinatura do ambiente: o de produção ou, no [ambiente de testes](/docs/ambientes-e-testes), o de teste. A verificação da assinatura garante que a requisição foi enviada pelo BotaPix e que o corpo não foi alterado. ## Algoritmo ```text X-BotaPix-Signature: sha256=