# 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"
QR Code Pix
Abra o app do banco e escaneie o QR Code.

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= = hex(HMAC-SHA256(secret, corpo da requisição)) ``` 1. Leia o corpo bruto da requisição, antes de qualquer conversão de JSON. 2. Calcule o HMAC-SHA256 do corpo com o secret e prefixe o resultado com `sha256=`. 3. Compare com o header `X-BotaPix-Signature` usando comparação em tempo constante. 4. Em caso de divergência, responda `401` sem processar o evento. ```php title="PHP" $payload = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_BOTAPIX_SIGNATURE'] ?? ''; $expected = 'sha256=' . hash_hmac('sha256', $payload, getenv('BOTAPIX_WEBHOOK_SECRET')); if (! hash_equals($expected, $signature)) { http_response_code(401); exit; } $event = json_decode($payload, true); ``` ```js title="Node.js" import crypto from 'node:crypto'; import express from 'express'; const app = express(); app.post('/webhooks/botapix', express.raw({ type: 'application/json' }), (req, res) => { const received = Buffer.from(req.get('X-BotaPix-Signature') ?? ''); const expected = Buffer.from( 'sha256=' + crypto.createHmac('sha256', process.env.BOTAPIX_WEBHOOK_SECRET).update(req.body).digest('hex'), ); if (received.length !== expected.length || ! crypto.timingSafeEqual(received, expected)) { return res.sendStatus(401); } const event = JSON.parse(req.body); res.sendStatus(200); }); ``` ```python title="Python" import hashlib import hmac import os from flask import Flask, abort, request app = Flask(__name__) @app.post("/webhooks/botapix") def botapix_webhook(): payload = request.get_data() received = request.headers.get("X-BotaPix-Signature", "") expected = "sha256=" + hmac.new( os.environ["BOTAPIX_WEBHOOK_SECRET"].encode(), payload, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(received, expected): abort(401) event = request.get_json() return "", 200 ``` Em aplicações Laravel, use `$request->getContent()` para obter o corpo bruto. Em Express, registre a rota com `express.raw` antes de qualquer `express.json()` global. ## Headers enviados | Header | Conteúdo | |---|---| | `Content-Type` | `application/json` | | `X-BotaPix-Signature` | `sha256=` seguido do HMAC-SHA256 do corpo, em hexadecimal. | | `X-BotaPix-Event-Id` | Igual a `event_id`. Mantido em todas as tentativas. | | `X-BotaPix-Timestamp` | Igual a `timestamp`. Mantido em todas as tentativas. | | `X-BotaPix-Delivery-Attempt` | Número da tentativa, de `1` a `8`. | ## Troca do secret Durante a [troca do secret](/docs/webhooks/configurar#troca-do-secret), aceite a assinatura de qualquer um dos dois secrets. Depois de ativar o novo no dashboard, remova o antigo. ```php title="PHP" $secrets = array_filter([getenv('BOTAPIX_WEBHOOK_SECRET'), getenv('BOTAPIX_WEBHOOK_SECRET_NEXT')]); $valid = false; foreach ($secrets as $secret) { $valid = $valid || hash_equals('sha256=' . hash_hmac('sha256', $payload, $secret), $signature); } if (! $valid) { http_response_code(401); exit; } ``` ## Divergência de assinatura | Causa | Solução | |---|---| | Novo secret ativado | Atualize o secret no servidor. Retentativas passam a ser assinadas com o novo secret. | | Corpo convertido antes da verificação | Verifique sobre o corpo bruto, antes de middlewares de JSON. | | Espaços ou quebras de linha no segredo | Remova caracteres adicionais da variável de ambiente. | O botão **Enviar teste** de cada endpoint em [Dashboard → API](/dashboard/api) exibe o status retornado e permite validar a verificação sem aguardar um pagamento. --- # Retentativas Fonte: https://botapix.com/docs/webhooks/retry-policy # Retentativas Uma entrega é confirmada quando o endpoint responde com status `2xx` em até 10 segundos. Qualquer outro resultado agenda uma nova tentativa com o mesmo `event_id`: - status `3xx`, `4xx` ou `5xx`; - tempo de resposta superior a 10 segundos; - falha de conexão, DNS ou certificado TLS. ## Calendário | Tentativa | Intervalo desde a anterior | Tempo desde o evento | |---|---|---| | 1 | imediata | 0 | | 2 | 30 segundos | 30 s | | 3 | 2 minutos | 2 min 30 s | | 4 | 10 minutos | 12 min 30 s | | 5 | 30 minutos | 42 min 30 s | | 6 | 2 horas | 2 h 42 min | | 7 | 6 horas | 8 h 42 min | | 8 | 24 horas | 32 h 42 min | O número da tentativa é informado no header `X-BotaPix-Delivery-Attempt`. Os horários podem variar alguns segundos conforme a fila de envio. ## Após a última tentativa Após a oitava tentativa sem confirmação, o evento deixa de ser reenviado. O pagamento e o saldo não são afetados. Cada endpoint tem as próprias retentativas: a falha em um não atrasa a entrega nos demais. Um endpoint com 50 tentativas com falha seguidas é [desativado automaticamente](/docs/webhooks/configurar#desligamento-automatico). Para garantir a consistência, execute uma conciliação periódica com [Listar cobranças](/docs/cobrancas/listar), filtrando por `status=paid` e pelas cobranças criadas nos dois dias anteriores, e com [Listar assinaturas](/docs/assinaturas/consultar#listar-assinaturas). ## Latência O evento é enviado assim que o pagamento é confirmado pela instituição financeira, em geral poucos segundos após o pagamento. --- # Testar localmente Fonte: https://botapix.com/docs/webhooks/testar-localmente # Testar localmente Os endpoints precisam de uma URL HTTPS pública, então `localhost` não pode ser cadastrado diretamente. Para receber eventos num servidor em execução na sua máquina, exponha a porta local com um túnel HTTPS e cadastre o endereço gerado como endpoint. ## Com Cloudflare Tunnel O `cloudflared` cria um endereço temporário em `trycloudflare.com`, sem conta. ```bash title="Terminal" cloudflared tunnel --url http://localhost:3000 ``` O comando exibe um endereço como `https://exemplo-aleatorio.trycloudflare.com`. Cadastre o endpoint com o caminho da rota que recebe os eventos, por exemplo `https://exemplo-aleatorio.trycloudflare.com/webhooks/botapix`. ## Com ngrok ```bash title="Terminal" ngrok http 3000 ``` Use o endereço `https://` exibido em **Forwarding**, também seguido do caminho da rota. ## Fluxo de teste 1. Inicie o servidor local e o túnel. 2. Em [Dashboard → API](/dashboard/api), na aba **Webhooks**, cadastre o endereço do túnel como um endpoint novo. 3. Use **Enviar teste** no endpoint. O painel mostra o status retornado e o tempo de resposta. 4. Abra a entrega em **Entregas** para conferir o corpo, os headers e a resposta do seu servidor. 5. Ao terminar, desative ou remova o endpoint do túnel. Endereços temporários mudam a cada execução, e um endpoint que falha 50 vezes seguidas é desativado. ## Problemas comuns | Sintoma | Causa provável | |---|---| | `401` no evento de teste | A verificação de assinatura usa outro secret ou lê o corpo já convertido. Consulte [Verificação HMAC](/docs/webhooks/assinatura-hmac). | | Sem resposta em 10 segundos | O servidor processa o evento antes de responder. Responda `2xx` e processe em segundo plano. | | Redirecionamento (`3xx`) | O túnel aponta para HTTP e o servidor redireciona para HTTPS, ou a rota exige barra no final. Cadastre o endereço final. | | URL recusada no cadastro | O endereço não usa HTTPS ou aponta para uma rede privada. Use o endereço público do túnel. | O túnel serve para desenvolvimento. Em produção, cadastre a URL definitiva do seu servidor. --- # payment.confirmed Fonte: https://botapix.com/docs/eventos/payment-confirmed # payment.confirmed Enviado quando um pagamento é confirmado e o valor líquido é creditado no saldo da conta. É o evento que libera o pedido. ## Quando é enviado - Para todas as cobranças da conta, criadas pela API ou não. O atributo `data.source` identifica a origem. - Uma vez por cobrança. Retentativas usam o mesmo `event_id`. - Para a `notification_url` da cobrança, quando informada; senão, para cada endpoint ativo que assina o evento. - No ambiente de testes, após a simulação de pagamento, com `livemode: false`. ```json title="payment.confirmed" { "event": "payment.confirmed", "event_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789", "livemode": true, "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", "metadata": {"loja": "centro", "canal": "site"}, "tracking": {"utm_source": "instagram", "utm_campaign": "black-friday"}, "paid_at": "2026-09-13T14:35:12+00:00" }, "timestamp": "2026-09-13T14:35:13+00:00" } ``` ## Atributos - `id` (integer): Identificador da cobrança. - `reference` (string): Identificador público da cobrança. - `external_reference` (string, nulo): Identificador informado na criação da cobrança ou da assinatura. - `source` (string): Origem do pagamento: `api`, `subscription`, `dashboard`, `donation`, `campaign`, `product` ou `discord`. Consulte [Origem do pagamento](/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): Valor pago, em centavos. - `fee` (integer): Tarifa, em centavos. - `net_amount` (integer): Valor líquido creditado, em centavos. - `status` (string): `paid`. - `metadata` (object, nulo): O `metadata` informado na [criação da cobrança](/docs/cobrancas/criar). `null` nos demais pagamentos. - `tracking` (object, nulo): Origem de campanha: UTMs e ids de clique da venda, quando houver. - `paid_at` (string): Data e hora da confirmação do pagamento. ## Como tratar 1. [Verifique a assinatura](/docs/webhooks/assinatura-hmac) e descarte eventos já processados pelo `event_id`. 2. Localize o pedido pelo `external_reference` ou pelo `metadata`. 3. Confira `amount_paid` com o valor esperado do pedido. 4. Libere o pedido e responda `2xx` em até 10 segundos; processos demorados ficam para uma fila. > **Retorno do pagador** > > O retorno do pagador pela `redirect_url` não confirma o pagamento. Libere o pedido somente após este evento ou após [consultar a cobrança](/docs/cobrancas/consultar) com status `paid`. --- # payment.refunded Fonte: https://botapix.com/docs/eventos/payment-refunded # payment.refunded Enviado quando o valor integral de um pagamento é devolvido ao pagador, por devolução ou por MED (Mecanismo Especial de Devolução). O valor é debitado do saldo da conta. ## Quando é enviado - Somente na devolução integral. Devoluções parciais não geram o evento. - Em [devoluções pela API](/docs/dinheiro/devolucoes), quando as devoluções concluídas alcançam o valor pago. Cada devolução também gera [`refund.completed`](/docs/eventos/refund-completed). - Uma vez por cobrança, com o mesmo `event_id` nas retentativas. - No ambiente de testes, após a simulação de devolução integral, com `livemode: false`. ```json title="payment.refunded" { "event": "payment.refunded", "event_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "livemode": true, "data": { "id": 1042, "reference": "k7Qm2xP9vT4wLr8sN1bZ6cYd3fHj5aGe", "external_reference": "pedido_1042", "source": "api", "subscription_id": null, "amount": 2990, "amount_paid": 2990, "fee": 90, "net_amount": 2900, "status": "refunded", "metadata": {"loja": "centro", "canal": "site"}, "paid_at": "2026-09-13T14:35:12+00:00", "refunded_at": "2026-09-15T10:12:00+00:00" }, "timestamp": "2026-09-15T10:12:01+00:00" } ``` ## Atributos Os mesmos de [`payment.confirmed`](/docs/eventos/payment-confirmed), com `status` igual a `refunded` e o atributo adicional: - `refunded_at` (string): Data e hora da conclusão da devolução. ## Como tratar 1. Localize o pedido pelo `external_reference` ou pelo `metadata`. 2. Reverta a entrega: cancele o acesso, o crédito ou o envio, conforme o seu negócio. 3. Registre `refunded_at` para a conciliação. --- # payment.expired Fonte: https://botapix.com/docs/eventos/payment-expired # payment.expired Enviado quando uma cobrança vence (`expires_at`) sem ser paga. A cobrança não pode mais ser paga; para cobrar de novo, crie outra. ## Quando é enviado - Para cobranças pendentes que passam do prazo. Ciclos de assinatura não geram o evento. - Pode chegar alguns minutos depois de `expires_at`. - No ambiente de testes, após a simulação de expiração, com `livemode: false`. ```json title="payment.expired" { "event": "payment.expired", "event_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b", "livemode": true, "data": { "id": 1043, "reference": "p2Lx8cV4nB6mQ1wE9rT3yU7iO5aS0dFg", "external_reference": "pedido_1043", "source": "api", "subscription_id": null, "amount": 2990, "amount_paid": null, "fee": 90, "net_amount": 2900, "status": "expired", "metadata": {"loja": "centro", "canal": "site"}, "paid_at": null, "expires_at": "2026-09-13T15:30:00+00:00" }, "timestamp": "2026-09-13T15:30:41+00:00" } ``` ## Atributos Os mesmos de [`payment.confirmed`](/docs/eventos/payment-confirmed), com `status` igual a `expired`, `amount_paid` e `paid_at` nulos, e o atributo adicional: - `expires_at` (string): Data e hora em que a cobrança venceu. ## Como tratar - Libere o estoque reservado para o pedido ou cancele-o. - Para o pagador tentar de novo, crie uma cobrança nova e envie a nova `payment_url`. --- # subscription.activated Fonte: https://botapix.com/docs/eventos/subscription-activated # subscription.activated Enviado quando o pagador autoriza uma [assinatura](/docs/assinaturas/criar) no aplicativo do banco. O status passa a `active` e os débitos mensais começam na data de início. ```json title="subscription.activated" { "event": "subscription.activated", "event_id": "5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "livemode": true, "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "external_reference": "assinante_207", "source": "api", "status": "active", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva" }, "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" }, "timestamp": "2026-09-13T14:41:08+00:00" } ``` ## Atributos - `id` (integer): Identificador da assinatura. - `reference` (string): Identificador da recorrência no Pix Automático. - `external_reference` (string, nulo): Identificador informado na criação. - `source` (string): Origem da assinatura: `api` para assinaturas criadas pela API e `donation` para as criadas na página pública da conta. - `status` (string): `active`. - `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`. - `customer.name` (string): Nome do pagador. - `start_date` (string): Data de início. - `end_date` (string, nulo): Data de término. - `approved_at` (string): Data e hora da autorização. - `canceled_at` (string, nulo): `null`. - `created_at` (string): Data e hora de criação. O CPF ou CNPJ do pagador não é enviado nos eventos e pode ser obtido em [Consultar assinatura](/docs/assinaturas/consultar). ## Como tratar - Ative o plano do assinante identificado por `external_reference`. - Cada débito mensal gera um [`payment.confirmed`](/docs/eventos/payment-confirmed) com `source: subscription` e o `subscription_id`. --- # subscription.rejected Fonte: https://botapix.com/docs/eventos/subscription-rejected # subscription.rejected Enviado quando o pagador ou a instituição financeira recusa a autorização de uma [assinatura](/docs/assinaturas/criar). O status passa a `rejected` e nenhum débito é feito. Uma assinatura recusada gera este evento sem `subscription.activated` anterior. Os atributos de `data` são os mesmos de [`subscription.activated`](/docs/eventos/subscription-activated), com `status` igual a `rejected` e `approved_at` nulo. ```json title="subscription.rejected" { "event": "subscription.rejected", "event_id": "6d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a", "livemode": true, "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "external_reference": "assinante_207", "source": "api", "status": "rejected", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva" }, "start_date": "2026-10-01", "end_date": null, "approved_at": null, "canceled_at": null, "created_at": "2026-09-13T14:30:00+00:00" }, "timestamp": "2026-09-13T14:52:30+00:00" } ``` ## Como tratar - Mantenha o plano inativo e avise o assinante. - Para tentar de novo, crie uma nova assinatura e envie o novo copia-e-cola de autorização. --- # subscription.canceled Fonte: https://botapix.com/docs/eventos/subscription-canceled # subscription.canceled Enviado quando uma [assinatura](/docs/assinaturas/criar) é cancelada pela API, pelo pagador ou pela instituição financeira. O status passa a `canceled` e os débitos seguintes não acontecem. Os atributos de `data` são os mesmos de [`subscription.activated`](/docs/eventos/subscription-activated), com `status` igual a `canceled` e `canceled_at` preenchido. Uma assinatura cancelada pela API antes da autorização gera somente este evento. ```json title="subscription.canceled" { "event": "subscription.canceled", "event_id": "7e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b", "livemode": true, "data": { "id": 207, "reference": "RR0908935620261001a1b2c3d4e5f", "external_reference": "assinante_207", "source": "api", "status": "canceled", "amount": 2500, "periodicity": "MENSAL", "customer": { "name": "João Silva" }, "start_date": "2026-10-01", "end_date": null, "approved_at": "2026-09-13T14:41:07+00:00", "canceled_at": "2026-11-20T09:15:00+00:00", "created_at": "2026-09-13T14:30:00+00:00" }, "timestamp": "2026-11-20T09:15:01+00:00" } ``` ## Como tratar - Encerre o plano do assinante ao fim do período já pago. - Um ciclo já debitado antes do cancelamento continua pago: o [`payment.confirmed`](/docs/eventos/payment-confirmed) dele não é desfeito. --- # webhook.test Fonte: https://botapix.com/docs/eventos/webhook-test # webhook.test Enviado pelo botão **Enviar teste** de um endpoint em [Dashboard → API](/dashboard/api), somente para aquele endpoint, para validação da URL e da verificação de assinatura. Não requer processamento. ```json title="webhook.test" { "event": "webhook.test", "event_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "livemode": true, "data": { "message": "Evento de teste enviado pelo painel do BotaPix." }, "timestamp": "2026-09-13T16:00:00+00:00" } ``` - O evento de teste tem uma única tentativa e não conta para o [desligamento automático](/docs/webhooks/configurar#desligamento-automatico) do endpoint. - É enviado ao endpoint mesmo que ele não assine o evento. - Responda `2xx` para o teste aparecer como entregue. --- # withdrawal.scheduled Fonte: https://botapix.com/docs/eventos/withdrawal-scheduled # withdrawal.scheduled Enviado quando um saque ganha data de envio: logo após o pedido ou após a aprovação. Vale para saques pedidos pela [API](/docs/dinheiro/saques) ou pelo dashboard. ```json title="withdrawal.scheduled" { "event": "withdrawal.scheduled", "event_id": "f6ac74ce-ba5d-5122-b34c-1318e0d92635", "livemode": true, "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" }, "timestamp": "2026-10-23T20:31:05+00:00" } ``` Os atributos de `data` são os do saque, descritos em [Saques](/docs/dinheiro/saques). ## Como tratar - O Pix sai a partir de `process_after`. --- # withdrawal.completed Fonte: https://botapix.com/docs/eventos/withdrawal-completed # withdrawal.completed Enviado quando o Pix do saque é enviado para a chave da conta. Vale para saques pedidos pela [API](/docs/dinheiro/saques) ou pelo dashboard. ```json title="withdrawal.completed" { "event": "withdrawal.completed", "event_id": "fee5fb0e-df64-54d6-a4e0-5150a4b198e4", "livemode": true, "data": { "id": 318, "status": "completed", "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": "2026-10-23T20:31:04+00:00", "failed_at": null, "canceled_at": null, "created_at": "2026-10-23T14:30:00+00:00" }, "timestamp": "2026-10-23T20:31:05+00:00" } ``` Os atributos de `data` são os do saque, descritos em [Saques](/docs/dinheiro/saques). ## Como tratar - Registre `completed_at` para conciliar com o extrato. --- # withdrawal.failed Fonte: https://botapix.com/docs/eventos/withdrawal-failed # withdrawal.failed Enviado quando o saque não é realizado. O valor volta para o saldo disponível. Vale para saques pedidos pela [API](/docs/dinheiro/saques) ou pelo dashboard. ```json title="withdrawal.failed" { "event": "withdrawal.failed", "event_id": "654bbc11-3a80-56c2-b9d7-ec1ee06287c9", "livemode": true, "data": { "id": 318, "status": "failed", "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": "2026-10-23T20:31:04+00:00", "canceled_at": null, "created_at": "2026-10-23T14:30:00+00:00" }, "timestamp": "2026-10-23T20:31:05+00:00" } ``` Os atributos de `data` são os do saque, descritos em [Saques](/docs/dinheiro/saques). ## Como tratar - Confira a chave Pix cadastrada e solicite um novo saque. --- # withdrawal.canceled Fonte: https://botapix.com/docs/eventos/withdrawal-canceled # withdrawal.canceled Enviado quando o saque é cancelado antes do envio. O valor volta para o saldo disponível. Vale para saques pedidos pela [API](/docs/dinheiro/saques) ou pelo dashboard. ```json title="withdrawal.canceled" { "event": "withdrawal.canceled", "event_id": "8f9e0d1c-2b3a-4c5d-6e7f-8091a2b3c4d5", "livemode": true, "data": { "id": 318, "status": "canceled", "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": "2026-10-23T16:00:00+00:00", "created_at": "2026-10-23T14:30:00+00:00" }, "timestamp": "2026-10-23T20:31:05+00:00" } ``` Os atributos de `data` são os do saque, descritos em [Saques](/docs/dinheiro/saques). ## Como tratar - Solicite um novo saque, se for o caso. --- # refund.completed Fonte: https://botapix.com/docs/eventos/refund-completed # refund.completed Enviado quando a devolução é concluída e o valor chega ao pagador. Vale para devoluções pedidas pela [API](/docs/dinheiro/devolucoes) ou pelo dashboard. ```json title="refund.completed" { "event": "refund.completed", "event_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "livemode": true, "data": { "id": 91, "charge_id": 1042, "status": "completed", "livemode": true, "amount": 2990, "reason": "Pedido cancelado", "created_at": "2026-10-23T14:30:00+00:00", "completed_at": "2026-10-23T14:30:04+00:00", "failed_at": null, "failure_reason": null }, "timestamp": "2026-10-23T14:30:05+00:00" } ``` Os atributos de `data` são os da devolução, descritos em [Devoluções](/docs/dinheiro/devolucoes). ## Como tratar - Registre `completed_at` e marque o pedido como devolvido. - Para devoluções parciais, some os valores: a cobrança só passa para `refunded`, com o evento [`payment.refunded`](/docs/eventos/payment-refunded), quando as devoluções alcançam o valor pago. --- # refund.failed Fonte: https://botapix.com/docs/eventos/refund-failed # refund.failed Enviado quando a devolução não é realizada. O valor volta para o saldo disponível. Vale para devoluções pedidas pela [API](/docs/dinheiro/devolucoes) ou pelo dashboard. ```json title="refund.failed" { "event": "refund.failed", "event_id": "d5148144-8f6c-5bd7-86c3-829cbcfe4db7", "livemode": true, "data": { "id": 91, "charge_id": 1042, "status": "failed", "livemode": true, "amount": 2990, "reason": "Pedido cancelado", "created_at": "2026-10-23T14:30:00+00:00", "completed_at": null, "failed_at": "2026-10-23T14:30:04+00:00", "failure_reason": "A devolução não foi realizada e o valor voltou para o saldo disponível." }, "timestamp": "2026-10-23T14:30:05+00:00" } ``` Os atributos de `data` são os da devolução, descritos em [Devoluções](/docs/dinheiro/devolucoes). ## Como tratar - Avise o cliente e, se for o caso, solicite uma nova devolução. - O valor já está de volta no saldo disponível, com o lançamento `refund_returned` no [extrato](/docs/dinheiro/saldo-e-extrato). --- # dispute.opened Fonte: https://botapix.com/docs/eventos/dispute-opened # dispute.opened Enviado quando o banco do pagador abre uma disputa (MED) sobre um pagamento. O valor contestado é bloqueado no saldo. ```json title="dispute.opened" { "event": "dispute.opened", "event_id": "17c84e01-ba69-53a6-a3f3-efced5bad06b", "livemode": true, "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 }, "timestamp": "2026-10-23T14:30:05+00:00" } ``` Os atributos de `data` são os da disputa, descritos em [Disputas (MED)](/docs/dinheiro/disputas). ## Como tratar - Suspenda a entrega do pedido, se ainda não foi feita. - Se a transação é legítima, envie as informações que a comprovam pelo suporte do dashboard antes de `analysis_due_at`. Consulte [Como responder](/docs/dinheiro/disputas#como-responder). --- # dispute.updated Fonte: https://botapix.com/docs/eventos/dispute-updated # dispute.updated Enviado quando a disputa passa para análise. ```json title="dispute.updated" { "event": "dispute.updated", "event_id": "3cc0fd3a-90d5-59d0-a02b-795473ac2b7c", "livemode": true, "data": { "id": 57, "charge_id": 1042, "status": "under_review", "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 }, "timestamp": "2026-10-23T14:30:05+00:00" } ``` Os atributos de `data` são os da disputa, descritos em [Disputas (MED)](/docs/dinheiro/disputas). ## Como tratar - Atualize o status da disputa no seu sistema. O valor continua bloqueado. --- # dispute.closed Fonte: https://botapix.com/docs/eventos/dispute-closed # dispute.closed Enviado quando a disputa é encerrada. O `status` indica o resultado. ```json title="dispute.closed" { "event": "dispute.closed", "event_id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b", "livemode": true, "data": { "id": 57, "charge_id": 1042, "status": "won", "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": "2026-10-28T10:00:00+00:00" }, "timestamp": "2026-10-23T14:30:05+00:00" } ``` Os atributos de `data` são os da disputa, descritos em [Disputas (MED)](/docs/dinheiro/disputas). ## Como tratar - `won` e `canceled`: o valor volta para o saldo disponível. Retome o pedido, se estava suspenso. - `lost`: o valor é devolvido ao pagador. Trate como uma devolução: cancele o acesso, o crédito ou o envio. --- # delivery.completed Fonte: https://botapix.com/docs/eventos/delivery-completed # delivery.completed Enviado quando a venda de um [produto](/docs/produtos/catalogo) é entregue ao comprador, logo depois do [`payment.confirmed`](/docs/eventos/payment-confirmed). Vale para vendas pela API, pelo link de compra e pela Loja no Discord. Uma cobrança criada com `notification_url` envia este evento para essa URL. ```json title="delivery.completed" { "event": "delivery.completed", "event_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "livemode": true, "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" }, "timestamp": "2026-10-23T14:31:03+00:00" } ``` Os atributos de `data` são os da entrega, descritos em [Vender um produto](/docs/produtos/vender#consultar-a-entrega), sem `content`. ## Como tratar - Marque o pedido como entregue pelo `charge_id` ou pelo `external_reference` da cobrança. - Para obter as chaves ou o link entregues, consulte `GET /api/v1/charges/{charge_id}/delivery`. O conteúdo não trafega no webhook. --- # delivery.failed Fonte: https://botapix.com/docs/eventos/delivery-failed # delivery.failed Enviado quando a venda de um produto `license_keys` é paga e o estoque não tem todas as chaves da compra. O comprador recebe as chaves disponíveis, e `missing` informa quantas faltaram. O dashboard também avisa a conta por e-mail. ```json title="delivery.failed" { "event": "delivery.failed", "event_id": "8d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "livemode": true, "data": { "charge_id": 1043, "product_id": "prod_8k2m4q7x1z9c3v5b", "product_name": "Licença anual", "quantity": 2, "status": "failed", "missing": 1, "url": "https://botapix.com/entrega/Yr4...", "buyer_email": "cliente@exemplo.com", "emailed_at": "2026-10-23T14:31:02+00:00", "delivered_at": null, "created_at": "2026-10-23T14:31:01+00:00" }, "timestamp": "2026-10-23T14:31:03+00:00" } ``` ## Como tratar - [Adicione chaves](/docs/produtos/catalogo#adicionar-chaves) ao produto e envie ao comprador as que faltaram, ou [devolva o pagamento](/docs/dinheiro/devolucoes). - A entrega não é refeita automaticamente quando o estoque é reposto. --- # Controles de alerta Fonte: https://botapix.com/docs/streamers/controle-de-alertas # Controles de alerta `POST https://botapix.com/api/remote/v1/{grupo}/{ação}` Os comandos controlam os widgets de alertas, de Media Share e de pedidos de música em execução no software de transmissão. São indicados para Stream Deck, atalhos de teclado e automações, e aplicam-se a todos os widgets ativos da conta. ```bash title="cURL" curl -X POST https://botapix.com/api/remote/v1/alerts/pause \ -H "Authorization: Bearer $BOTAPIX_REMOTE_TOKEN" ``` ```php title="PHP" $client = new GuzzleHttp\Client(['base_uri' => 'https://botapix.com/api/remote/v1/']); $response = $client->post('alerts/pause', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('BOTAPIX_REMOTE_TOKEN')], ]); $result = json_decode($response->getBody(), true); ``` ```js title="Node.js" const response = await fetch('https://botapix.com/api/remote/v1/alerts/pause', { method: 'POST', headers: { Authorization: `Bearer ${process.env.BOTAPIX_REMOTE_TOKEN}` }, }); const result = await response.json(); ``` ```python title="Python" import os import requests response = requests.post( "https://botapix.com/api/remote/v1/alerts/pause", headers={"Authorization": f"Bearer {os.environ['BOTAPIX_REMOTE_TOKEN']}"}, ) result = response.json() ``` ```json title="200 OK" { "ok": true, "action": "alerts.pause", "state": { "paused": true, "muted": false, "media_paused": false, "music_paused": false } } ``` ## Autenticação Os comandos usam um token próprio, gerado em [Integrações → Stream Deck e controle remoto](/dashboard/integracoes) e enviado no header `Authorization`. O token começa com `bpxr_`, é restrito aos controles de alerta e não dá acesso a cobranças, assinaturas ou saques. ```http Authorization: Bearer bpxr_... ``` O token permite controlar os alertas e consultar as doações recentes. Revogue e gere um novo token em caso de exposição. ## Comandos | Endpoint | Efeito | |---|---| | `POST /api/remote/v1/alerts/pause` | Retém os próximos alertas na fila. | | `POST /api/remote/v1/alerts/resume` | Libera a fila. | | `POST /api/remote/v1/alerts/toggle` | Pausa ou libera a fila, conforme o estado atual. | | `POST /api/remote/v1/alerts/skip` | Remove da tela o alerta em exibição. | | `POST /api/remote/v1/alerts/replay` | Exibe novamente a última doação paga nas últimas 24 horas, com voz e mensagem. | | `POST /api/remote/v1/alerts/approve` | Com a aprovação manual ligada, envia para a live o alerta mais antigo que espera aprovação. | | `POST /api/remote/v1/alerts/reject` | Com a aprovação manual ligada, descarta o alerta mais antigo que espera aprovação. A doação continua paga. | | `POST /api/remote/v1/alerts/clear` | Esvazia a fila e remove o alerta em exibição. O histórico do dashboard é preservado. | | `POST /api/remote/v1/alerts/test` | Exibe um alerta de teste. | | `POST /api/remote/v1/tts/mute` | Silencia a voz sintetizada e os áudios gravados, inclusive durante a reprodução. | | `POST /api/remote/v1/tts/unmute` | Reativa as vozes. | | `POST /api/remote/v1/tts/toggle` | Silencia ou reativa as vozes, conforme o estado atual. | | `POST /api/remote/v1/media/pause` | Pausa o vídeo do Media Share em exibição e retém os próximos. O tempo comprado não é consumido durante a pausa. | | `POST /api/remote/v1/media/resume` | Retoma o vídeo e libera a fila do Media Share. | | `POST /api/remote/v1/media/toggle` | Pausa ou retoma o Media Share, conforme o estado atual. | | `POST /api/remote/v1/media/skip` | Encerra o vídeo em exibição. O pedido continua pago e não retorna à fila. | | `POST /api/remote/v1/media/clear` | Encerra o vídeo em exibição e os pedidos aprovados na fila. Pedidos em moderação ou aguardando pagamento não são afetados. | | `POST /api/remote/v1/media/replay` | Coloca de volta na fila o último vídeo exibido nas últimas 24 horas. | | `POST /api/remote/v1/music/pause` | Pausa a música em reprodução e retém os próximos pedidos de música. | | `POST /api/remote/v1/music/resume` | Retoma a música e libera a fila de pedidos de música. | | `POST /api/remote/v1/music/toggle` | Pausa ou retoma os pedidos de música, conforme o estado atual. | | `POST /api/remote/v1/music/skip` | Encerra a música em reprodução. O pedido continua pago e não retorna à fila. | | `POST /api/remote/v1/music/clear` | Encerra a música em reprodução e os pedidos aprovados na fila. | | `POST /api/remote/v1/music/replay` | Coloca de volta na fila a última música tocada nas últimas 24 horas. | | `GET /api/remote/v1/state` | Retorna o estado atual, sem alterações. | `pause`, `resume`, `mute` e `unmute` podem ser repetidos sem efeito adicional. `toggle`, `skip`, `clear`, `replay`, `approve`, `reject` e `test` executam a ação a cada chamada. Silenciar as vozes não interrompe o som nem a animação do alerta. As pausas dos vídeos e das músicas são independentes da pausa dos alertas. Os estados de pausa e de silêncio retornam ao padrão após 24 horas sem comandos. O estado atual também é exibido em Integrações. ## Corpo da requisição Os comandos não exigem corpo, com exceção do parâmetro opcional de `alerts/test`: - `amount` (number): Valor exibido no alerta de teste, em reais, de `1` a `10000`. Padrão: `10`. ## Resposta - `ok` (boolean): `true` quando o comando é aplicado. - `action` (string): Comando executado, no formato `grupo.ação`. - `state` (object): Estado após o comando. - `state.paused` (boolean): Indica se os alertas estão pausados. - `state.muted` (boolean): Indica se as vozes estão silenciadas. - `state.media_paused` (boolean): Indica se os vídeos do Media Share estão pausados. - `state.music_paused` (boolean): Indica se os pedidos de música estão pausados. - `replayed` (integer, nulo): Somente em `alerts/replay`, `media/replay` e `music/replay`: identificador da doação exibida novamente ou do pedido recolocado na fila, ou `null` quando não há item elegível. - `skipped` (integer): Somente em `media/skip`, `media/clear`, `music/skip` e `music/clear`: quantidade de pedidos encerrados. - `decided` (integer, nulo): Somente em `alerts/approve` e `alerts/reject`: identificador da doação cujo alerta foi aprovado ou recusado, ou `null` quando nenhum alerta espera aprovação. `GET /api/remote/v1/state` retorna `ok` e `state`, além da fila atual do widget em `queue`, das doações que podem ser repetidas em `recent` e dos alertas que esperam aprovação em `approvals`. ## Stream Deck 1. Instale um plugin de requisições HTTP, como Web Requests ou API Ninja. 2. Configure uma tecla por comando, com o método `POST` e a URL completa do comando. 3. Adicione o header `Authorization` com o valor `Bearer` seguido do token. ## Limites e erros Cada token pode enviar até 60 requisições por minuto. | Status | `error` | Descrição | |---|---|---| | `401` | `unauthorized` | Token ausente, inválido ou revogado. | | `403` | `forbidden` | Conta indisponível. | | `404` | `unknown_action` | Comando inexistente. Os comandos válidos são retornados em `actions`. | | `422` | | `amount` fora do intervalo permitido. | | `429` | | Limite de requisições excedido. | --- # Live de GTA 6 com Pix: maratona (subathon), voz e tema Neon Fonte: https://botapix.com/blog/live-de-gta-6-com-pix GTA 6 (Grand Theft Auto VI) saiu e, pelas próximas semanas, metade das lives brasileiras vai estar no mesmo mapa, nas mesmas missões. O jogo é igual para todo mundo. O que muda de uma live para outra é como a audiência participa. Na semana de lançamento, isso tem nome: **maratona**. A live só continua enquanto a comunidade doa, e cada Pix aparece na tela, é lido em voz alta e empurra o cronômetro para frente. **Resumo:** - **Maratona (subathon) com Pix:** um cronômetro no OBS que ganha tempo a cada doação, sub, bits ou Kicks. O padrão é 1 minuto por real. - **O alerta lê toda doação em voz alta** (TTS em português do Brasil), sem custo extra. - **Tema Neon** para o alerta: pôr do sol, coqueiros e estrelas que acendem conforme o valor. - Funciona na Twitch, na Kick e no YouTube. Custa 3% por doação, sem mensalidade. Quem doa não precisa de conta: paga o Pix pelo app do banco. ## Passo a passo rápido 1. Crie a conta e a página de doação (`botapix.com/s/seunome`). O [guia de Pix na live](/blog/como-receber-pix-na-live-guia-streamer) mostra cada tela. 2. Em **Minha Página → Widgets da live**, copie a URL do **Alerta** e a da **Maratona** em **Adicionar ao OBS** e cole cada uma como Browser Source. 3. No alerta, na aba **Voz**, ligue **Ler as doações em voz alta**. Abaixo da prévia, em **Temas**, escolha o **Neon**. 4. Na hora de abrir a live, inicie a maratona em **Ao vivo → Maratona**, com o tempo inicial e, se quiser, um teto de horas. 5. Clique em **Testar** no alerta, confira o volume da voz contra o som do jogo e divulgue o link no chat e no painel do canal. ## Maratona (subathon): a live dura o quanto a comunidade quiser Live de lançamento costuma virar maratona, e é aí que a doação mais aparece: cada Pix soma tempo num cronômetro na tela, e o chat vê o efeito na hora. Você define quanto vale cada coisa: | Evento | Padrão | |---|---| | Doação em Pix | 1 minuto por R$ 1 | | Sub (Twitch ou Kick) | 5 minutos por sub | | Bits | 1 minuto por 100 bits | | Kicks | 1 minuto por 100 Kicks | | Raid | desligado (dá para dar segundos por viewer) | - **A doação conta quando o Pix é pago**, não quando o QR Code é gerado. Vaquinha e assinatura mensal também somam. Sub, bits e raid somam com a [Twitch ou a Kick conectada](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs). - **Teto de horas:** com teto, o cronômetro nunca passa dele, por mais que entre dinheiro. É o que deixa você prometer "vai até no máximo 24 horas" e cumprir. - **Pausar, ajustar e encerrar** ficam em **Ao vivo**: pausar congela o relógio (a doação que chega pausada continua somando), ajustar soma ou tira minutos na mão. - **O widget** mostra o título, o cronômetro grande e a última adição ("+10m · Maria · R$ 10,00"), com um pulso a cada vez que entra tempo. - **Cinco estilos:** Relógio, Pílula, **Notificação** (um card escuro e translúcido, com o anel do tempo, que conversa com as notificações do próprio jogo), Anel e Faixa (uma tarja para a parte de baixo da tela). Em **Fundo**, você deixa o card mais ou menos transparente sobre o jogo. Quando o cronômetro zera, a maratona acabou: uma doação depois disso é uma doação normal e não traz o relógio de volta. Os detalhes estão no [guia da maratona](/blog/maratona-subathon-com-pix-como-configurar). **Ideias para GTA 6:** "zerar a história sem desligar", "a live acaba quando o cronômetro zerar ou quando eu morrer para a polícia", meta de horas com uma recompensa no fim. ## O alerta lê toda doação em voz alta (TTS) Em **Minha Página → Widgets da live → Alerta → Voz**, ligue **Ler as doações em voz alta**. A partir daí, toda doação é lida na live: quem mandou, o valor e a mensagem inteira. > "Marina mandou vinte e cinco reais. Primeira vez assistindo e já virei fã, valeu pelo conteúdo!" - **Três vozes em português do Brasil:** Vitória, Camila e Thiago. O ▶ ao lado de cada uma toca um exemplo antes de você escolher. - **Sem custo extra.** A leitura está incluída na taxa de 3% por doação. Não tem plano nem crédito para comprar. - **A mensagem inteira é lida**, mesmo quando o alerta encurta o texto na tela com "…". - **Mensagem barrada pelo filtro** (ofensa, ameaça) não é lida. A voz diz só quem mandou e quanto, e o alerta aparece normalmente. A leitura vem desligada: você escolhe se quer. Numa maratona de GTA, com o chat rápido e o jogo fazendo barulho, ela é o que faz a doação ser notada em vez de passar batido. ### Vozes de IA para quem doa mais À parte da leitura, você pode ligar **Vozes de IA (quem doa escolhe)**. A partir de um valor mínimo (o padrão é R$ 5), quem doa escolhe uma voz mais expressiva, de personagem inclusive, e nessa doação ela fala no lugar da leitura. Dá para escolher se a voz também lê o nome e o valor antes da mensagem. Também dá para deixar o doador **gravar um áudio** de até 20 segundos, que toca no lugar das vozes. ## Tema Neon: pôr do sol, coqueiros e estrelas pelo valor O alerta tem uma aba de **Temas** no seletor de estilo. O **Neon** foi feito para esta época: letreiro rosa que acende piscando, sol listrado nascendo no horizonte, chão em grade e coqueiros. O valor aparece num visor com cinco estrelas, que acendem conforme o tamanho da doação: | Doação | Estrelas | |---|---| | Até R$ 9,99 | ★ | | R$ 10 a R$ 24,99 | ★★ | | R$ 25 a R$ 49,99 | ★★★ | | R$ 50 a R$ 99,99 | ★★★★ | | R$ 100 ou mais | ★★★★★ | Sub, raid e os outros eventos da plataforma aparecem com três estrelas. Para usar, abra o alerta no painel, vá em **Temas** e clique em **Neon**. A prévia mostra como fica antes de ir para a live. Na aba **Estilos** estão os outros visuais, como o **Pixel**, uma caixa de diálogo de jogo antigo em que os óculos descem no gatinho. Se você usa **variações por valor**, dá para deixar o Neon só para doações grandes: até R$ 49 aparece o seu estilo de sempre e, a partir de R$ 50, o Neon. ## O chat escolhe a próxima missão: enquete Com a [enquete com Pix](/blog/enquetes-com-pix-na-live), a audiência vota pagando: "assalto ou missão da história?", "qual carro roubar agora?", "Jason ou Lucia na próxima?". Cada voto é uma doação, aparece no alerta e, com a maratona rodando, também soma tempo. ## Sub, bits e raid no mesmo alerta Conecte a [Twitch ou a Kick](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs) e sub, bits, raid e follow aparecem no mesmo alerta das doações, com o mesmo tema. Não precisa de um segundo sistema de alertas no OBS. ## Teste antes de abrir a live 1. O tamanho recomendado de cada widget aparece em **Adicionar ao OBS**: para o alerta Neon, 720 × 160. 2. Clique em **Testar** no painel. O teste aparece na prévia e no OBS e, com a leitura ligada, já fala com a voz que você escolheu. 3. Confira o volume da voz em relação ao som do jogo. O controle fica na aba **Voz**. ## Perguntas frequentes **Como funciona a subathon com Pix?** Cada doação em Pix soma tempo num cronômetro que aparece na live (o padrão é 1 minuto por real). Sub, bits e Kicks também somam com a Twitch ou a Kick conectada. Quando o cronômetro zera, a live acaba. Dá para pôr um teto de horas, pausar e ajustar o tempo na mão. **O que é live pix?** É receber doação em Pix durante a transmissão: o viewer paga pelo link ou pelo QR Code e a doação aparece num alerta na tela, com a mensagem dele. O [guia completo](/blog/como-receber-pix-na-live-guia-streamer) explica do zero. **Quanto custa?** 3% por doação, sem mensalidade. A maratona, a leitura em voz alta e os temas não custam nada a mais. O saque para a sua chave Pix tem tarifa de 1,5% (mínimo de R$ 0,50). **Funciona no YouTube e na Kick?** Sim. Os widgets são fontes do OBS e funcionam em qualquer plataforma. Conectar a Twitch ou a Kick só é preciso para sub, bits e raid. **O viewer precisa ter conta no BotaPix?** Não. Ele abre o seu link (`botapix.com/s/seunome`), escreve a mensagem e paga o Pix pelo app do banco. **Minha chave Pix aparece para quem doa?** Não. Quem doa paga para o BotaPix, e o dinheiro vai para o seu saldo. O saque sai só para uma chave Pix no seu CPF ou CNPJ. **Já uso outra plataforma de doação. Vale trocar?** Depende do seu volume. O [comparativo de taxas](/blog/botapix-vs-alternativas-comparativo-2026) mostra quanto de cada R$ 1.000 doado chega na sua conta em cada plataforma. ## Leia também - [Maratona (subathon) com Pix, subs e bits: como configurar](/blog/maratona-subathon-com-pix-como-configurar) - [Como receber Pix na live: o guia completo](/blog/como-receber-pix-na-live-guia-streamer) - [Enquetes com Pix: a audiência decide, e paga por isso](/blog/enquetes-com-pix-na-live) - [5 erros que reduzem doações na sua live](/blog/5-erros-que-reduzem-doacoes-na-live) --- # Sub, bits e raid da Twitch e da Kick no mesmo alerta do Pix Fonte: https://botapix.com/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs Até agora o widget de alerta do BotaPix só falava de Pix. Quem fazia live na Twitch ou na Kick precisava de um segundo sistema de alertas para sub, bits e raid, com outro visual, outro som e outra fonte no OBS. Agora é uma coisa só: **conecte sua conta e os eventos da plataforma aparecem no mesmo widget das doações**, com a mesma identidade visual. ## O que vira alerta | Twitch | Kick | |---|---| | Sub novo, resub (com meses) e subs presenteadas | Sub novo, renovação e subs presenteadas | | Bits (com mínimo configurável) | Kicks (com mínimo configurável) | | Raid (com número de viewers) | Follow | | Follow | | Cada tipo tem um toggle. Follows vêm desligados por padrão porque em canal grande viram spam; ligue se fizer sentido para o seu tamanho. ## Como conectar Se você ainda não tem a página de doação e o widget de alerta no OBS, comece pelo [guia de Pix na live](/blog/como-receber-pix-na-live-guia-streamer); leva uns dez minutos. Com isso pronto: 1. Em **Integrações**, clique em **Conectar** na Twitch ou na Kick. 2. Autorize na plataforma. O BotaPix pede só os escopos de leitura de sub, bits e follows; nada de escrever no seu canal. 3. Volte para a aba **Alertas**. Embaixo do preview aparece o card da plataforma com os toggles e o mínimo de bits ou Kicks. Pronto. O widget que já está no OBS passa a receber os eventos, sem trocar a URL. ## O que aparece no alerta O alerta mostra o nome de quem fez a ação, o verbo certo e o rótulo no lugar do valor: "ana mandou 500 bits", "rico presenteou 5 subs Tier 1", "outro raidou com 120 viewers". Sub presenteada conta uma vez, pelo presente, e não uma vez por presenteado. Sub anônimo e bits anônimos aparecem como "Anônimo", como manda a plataforma. Ficou barulhento demais num momento sério da live? Dá para pausar, pular ou silenciar o alerta com uma tecla do [Stream Deck](/blog/stream-deck-pausar-pular-e-silenciar-alertas), sem sair do jogo. ## Dinheiro não passa por aqui Vale deixar claro: **nenhum valor de sub ou bits passa pelo BotaPix**. A Twitch e a Kick continuam pagando você como sempre. A integração só recebe a notificação do evento e mostra o alerta. Por isso não tem taxa nenhuma nisso. ## Se você usa StreamLabs A alert box do StreamLabs já mostra sub e bits da Twitch por conta própria. Se você usa as duas coisas na cena, o mesmo evento vai aparecer nos dois lugares. Escolha um: ou desliga os toggles no BotaPix, ou tira a alert box do StreamLabs. ## E a maratona Com a Twitch ou a Kick conectada, sub, bits e raid também somam tempo na [maratona](/blog/maratona-subathon-com-pix-como-configurar), cada um com a sua regra de segundos. ## Leia também - [Maratona (subathon) com Pix, subs e bits](/blog/maratona-subathon-com-pix-como-configurar) - [Stream Deck: pausar, pular e silenciar alertas](/blog/stream-deck-pausar-pular-e-silenciar-alertas) - [Como receber Pix na live: o guia completo](/blog/como-receber-pix-na-live-guia-streamer) --- # App BotaPix para Android: receba Pix na live e acompanhe tudo pelo celular Fonte: https://botapix.com/blog/app-botapix-android-mapa-irl-ao-vivo O app BotaPix para Android está publicado na [Google Play](https://play.google.com/store/apps/details?id=com.botapix.app). É o mesmo BotaPix do site, no bolso: quem já usa a plataforma para [receber Pix na live](/blog/como-receber-pix-na-live-guia-streamer) entra com a mesma conta e vê o saldo, saca e acompanha as doações pelo celular. A versão para iPhone está em desenvolvimento. ## Pra que serve um app de doação para streamer Live acontece longe do painel. Você está no jogo, no IRL na rua, ou só descansando no sofá depois da transmissão. O app resolve o que antes exigia abrir o site: - **Saldo na hora.** Disponível e retido, com a opção de esconder o valor na tela. - **Saque pelo celular.** O mesmo saque do site, para a sua chave Pix, com a mesma verificação de segurança. - **Histórico de recebimentos.** Doações, [assinaturas](/blog/assinaturas-pix-automatico-no-botapix) e cobranças, com o resumo dos últimos dias. - **Mapa IRL ao vivo.** O celular vira a fonte do trajeto que aparece no OBS. Tudo que você configura no site continua valendo: os alertas de Pix e de [sub, bits e raid da Twitch e da Kick](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs), a [maratona](/blog/maratona-subathon-com-pix-como-configurar), as [enquetes](/blog/enquetes-com-pix-na-live) e as [recompensas](/blog/recompensas-para-quem-doa-ou-assina) rodam do mesmo jeito, e o app mostra o dinheiro entrando. ## Mapa IRL: como transmitir 1. No painel, em **Minha Página → Mapa IRL**, copie a URL do widget e adicione como Fonte de Navegador no OBS. 2. No app, toque no botão central e escolha **Transmitir mapa**. 3. O trajeto aparece na live em tempo real. Quando você encerra no app, o mapa some sozinho. O rastreio só funciona pelo celular, porque é ele que tem o GPS. Sua localização só é enviada enquanto a transmissão estiver ligada. ## Privacidade no mapa O widget tem três modos: mapa completo, sem os nomes das ruas (mantém a malha viária, esconde os rótulos), e modo privado. Dá para ajustar zoom, tamanho, se desenha o trajeto e se mostra a velocidade. Em live na rua vale começar sem os nomes das ruas. O público vê que você está andando pela cidade sem saber a esquina exata. ## Receber Pix pelo celular sem expor sua chave O app não muda a regra que faz o BotaPix existir: quem doa paga para o BotaPix, e você saca para a sua chave Pix quando quiser. Sua chave nunca aparece para o público, nem no site, nem no app. O que muda é que agora o saque e o acompanhamento cabem na palma da mão. ## Instalar [BotaPix na Google Play](https://play.google.com/store/apps/details?id=com.botapix.app). Entre com a mesma conta do site. Ainda não tem conta? O [guia de Pix na live](/blog/como-receber-pix-na-live-guia-streamer) mostra o passo a passo para criar a página e começar a receber hoje. ## Leia também - [Como receber Pix na live: passo a passo para o streamer](/blog/como-receber-pix-na-live-guia-streamer) - [Sub, bits e raid da Twitch e da Kick no mesmo alerta](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs) - [Maratona (subathon) com Pix, subs e bits](/blog/maratona-subathon-com-pix-como-configurar) --- # Enquetes com Pix: a audiência decide, e paga por isso Fonte: https://botapix.com/blog/enquetes-com-pix-na-live "Qual jogo a gente joga hoje?" é a pergunta mais feita em live. Com a enquete do BotaPix, ela vira uma decisão da comunidade e uma fonte de doação ao mesmo tempo. ## Criar A enquete mora na sua página de doação, então o primeiro passo é ter a página no ar (o [guia para streamer](/blog/como-receber-pix-na-live-guia-streamer) resolve isso). Depois, em **Minha Página → Enquete**: a pergunta, de duas a seis opções, e como o voto conta: - **R$ 1 = 1 voto:** quem doa R$ 50 dá 50 votos. Bom para deixar a decisão proporcional ao apoio. - **1 doação = 1 voto:** cada Pix pago vale um voto, independente do valor. Bom para dar peso igual a todo mundo. Nos dois modos dá para exigir um **mínimo para votar**. No modo "1 doação = 1 voto" ele é o que impede uma enxurrada de R$ 1 decidir a enquete. Só existe uma enquete ativa por vez. Encerrou, ela vai para o histórico com os totais e você pode abrir outra. ## Como o doador vota Na sua página de doação aparece a pergunta com as opções em pílulas, junto com a porcentagem atual. A pessoa escolhe o valor, marca uma opção (ou não; votar é opcional) e paga o Pix. O voto **conta quando o Pix é pago**. QR Code gerado e não pago não vota. Se a doação for devolvida depois, o voto sai. Se a enquete encerrar entre a pessoa abrir a página e pagar, o Pix passa normalmente, só não vota. A enquete nunca bloqueia uma doação. ## O widget A aba tem a URL do widget para o OBS: pergunta, uma barra por opção, porcentagem e número de votos, e a opção líder em destaque. Atualiza sozinho a cada voto. No painel você vê, além dos votos, quanto cada opção arrecadou em reais. Esse valor não aparece no widget nem na página pública, só para você. ## Combina com - [Maratona](/blog/maratona-subathon-com-pix-como-configurar): a enquete escolhe o que vem a seguir, e o mesmo Pix soma tempo no cronômetro. - [Recompensas](/blog/recompensas-para-quem-doa-ou-assina): quem vota a partir de um valor pode levar um link ou conteúdo exclusivo junto. - [Alertas de sub, bits e raid](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs): tudo no mesmo widget, com a mesma cara. - [Guia de Pix na live](/blog/como-receber-pix-na-live-guia-streamer): se está começando agora. --- # Maratona (subathon) com Pix, subs e bits: como configurar Fonte: https://botapix.com/blog/maratona-subathon-com-pix-como-configurar Subathon é simples de explicar e difícil de operar: a live só continua enquanto a comunidade paga por mais tempo. O cronômetro precisa somar cada doação na hora, sem você mexer, e aguentar horas rodando. O BotaPix agora tem isso pronto em **Minha Página → Maratona**. Se você ainda não recebe Pix na live, o [guia para streamer](/blog/como-receber-pix-na-live-guia-streamer) mostra o básico antes: página, chave Pix e widget de alerta. ## Como o tempo entra Você define quantos segundos cada coisa vale: | Evento | Regra | Padrão | |---|---|---| | Doação em Pix | segundos por R$ 1 | 60 s (1 min por real) | | Sub (Twitch ou Kick) | segundos por sub | 300 s | | Bits | segundos por 100 bits | 60 s | | Kicks | segundos por 100 Kicks | 60 s | | Raid | segundos por viewer | desligado | Doação conta **quando o Pix é pago**, não quando o QR Code é gerado. Cobrança de assinatura paga também soma como doação. Pagamento vindo da API ou de venda não entra, porque não é apoio de live. Sub, bits e raid só entram com a [Twitch ou a Kick conectada](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs). Subs presenteadas somam uma vez por presente: 5 subs presenteadas valem 5 vezes a regra de sub. ## Iniciar, pausar, ajustar - **Iniciar** pede o tempo inicial em minutos e, opcionalmente, um **teto** em horas. Com teto, o cronômetro nunca passa dele, por mais que entre dinheiro. - **Pausar** congela o tempo (intervalo, queda de luz). Doação que chega pausada continua somando, só não corre o relógio. - **Ajustar** soma ou tira minutos na mão. É a única coisa que revive uma maratona que já zerou. - **Encerrar** fecha de vez. Quando o cronômetro chega a zero rodando, a maratona acabou. Uma doação que chega depois disso é uma doação normal e não ressuscita o relógio. Foi uma decisão de produto: o widget já mostrou "encerrada" para todo mundo, e voltar do nada confunde a audiência. ## O widget A aba Maratona tem a URL do widget para colar como Browser Source no OBS. Ele mostra o título, o cronômetro grande e a última adição ("+10m · Maria S. · R$ 10,00") com um pulso a cada vez que entra tempo. O relógio anda no próprio widget, sincronizado com o servidor, então não depende de conexão a cada segundo. Dá para esconder o título e a última adição nas opções do widget. ## Dica de operação Deixe o teto ligado em maratona longa. É o que garante que você consegue prometer "vai até no máximo 48 horas" e cumprir. Maratona combina com [enquete](/blog/enquetes-com-pix-na-live): a comunidade decide o que vem a seguir votando com Pix, e cada voto também vira tempo no cronômetro. E longe do PC, o [app do BotaPix](/blog/app-botapix-android-mapa-irl-ao-vivo) mostra o saldo e as doações chegando pelo celular. ## Leia também - [Live de GTA 6 com Pix: maratona, voz e tema Neon](/blog/live-de-gta-6-com-pix) - [Enquetes com Pix: a audiência decide, e paga por isso](/blog/enquetes-com-pix-na-live) - [Sub, bits e raid da Twitch e da Kick no mesmo alerta](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs) - [Como receber Pix na live: o guia completo](/blog/como-receber-pix-na-live-guia-streamer) --- # Recompensas: link, código ou conteúdo secreto para quem doa ou assina Fonte: https://botapix.com/blog/recompensas-para-quem-doa-ou-assina Discord VIP, wallpaper exclusivo, um código, um "obrigado" que só quem apoiou vê. Tudo isso já era possível na mão: o streamer via a doação, procurava o doador, mandava o link. Agora é automático. ## Como funciona 1. Em **Recompensas**, clique em **Nova recompensa**. 2. **O que o apoiador ganha:** título e descrição (os dois aparecem na página de doação), e a entrega, que pode ser um **link** ou um **texto secreto** (só quem ganhar vê). 3. **Quem ganha:** doação a partir de um valor, assinatura, ou os dois. 4. **Se uma doação desbloquear várias:** "entrega sempre" ou "é um nível". Explico abaixo. Na sua página de doação aparece uma linha "Recompensas" recolhida, que mostra o que a pessoa ganha com o valor que ela escolheu. Quem doa a partir do mínimo recebe a recompensa **na tela de confirmação do Pix**, com um link de resgate que fica valendo. Se o doador estiver logado no BotaPix, vai por e-mail também. ## Comum ou nível Imagine três recompensas: wallpaper a partir de R$ 10, Discord VIP a partir de R$ 50, call de 10 minutos a partir de R$ 100. - Marcadas como **entrega sempre**, quem doa R$ 60 ganha as duas primeiras. - Marcadas como **nível**, quem doa R$ 60 ganha só o Discord VIP, que é o maior nível desbloqueado. As de "entrega sempre" vão junto com qualquer outra. Dá para misturar: wallpaper como "sempre" e as outras duas como níveis. ## Assinatura Se você ainda não ativou o apoio mensal, veja como funcionam as [assinaturas com Pix Automático](/blog/assinaturas-pix-automatico-no-botapix). Recompensa marcada para assinatura libera **no primeiro ciclo pago** e continua valendo enquanto a assinatura estiver em dia. Se o assinante cancelar, a recompensa é revogada na hora. Se ele parar de pagar, ela cai depois do período mais uma tolerância de cinco dias. Se ele voltar a pagar, a mesma recompensa volta a valer, com o mesmo link. ## Devolução e revogação manual Doação devolvida, inclusive por MED, revoga o que ela tinha liberado. E você pode revogar qualquer entrega na mão, em **Entregas recentes**. A página de resgate passa a dizer que a recompensa não está mais disponível, sem mostrar o conteúdo. ## O que não fazer Não coloque como recompensa nada que não possa ser copiado. O link do Discord ou o código chega inteiro para quem pagou, e a partir daí é dele. Recompensa é o "obrigado" de quem apoiou. Para puxar o apoio na live em si, ela combina com a [enquete com Pix](/blog/enquetes-com-pix-na-live) e com a [maratona](/blog/maratona-subathon-com-pix-como-configurar), que dão motivo para doar agora. ## Leia também - [Assinaturas via Pix Automático: como cobrar todo mês](/blog/assinaturas-pix-automatico-no-botapix) - [Enquetes com Pix na live](/blog/enquetes-com-pix-na-live) - [Como receber Pix na live: o guia completo](/blog/como-receber-pix-na-live-guia-streamer) --- # Stream Deck: pausar, pular e silenciar os alertas com uma tecla Fonte: https://botapix.com/blog/stream-deck-pausar-pular-e-silenciar-alertas Você está no meio de uma fala séria e chega um alerta com TTS. Ou alguém mandou uma mensagem que não deveria tocar. Até agora a saída era ir no painel. Agora é uma tecla. ## O que dá para fazer | Tecla | O que acontece | |---|---| | Pausar / retomar | Alertas novos ficam na fila e saem quando você retomar | | Pular | Corta o alerta que está na tela | | Silenciar / ativar a voz | O alerta aparece, mas sem TTS nem áudio gravado | | Alerta de teste | O mesmo teste do botão do painel | Silenciar de verdade silencia: com a voz desligada o BotaPix nem gera o TTS daquele alerta. Vale para tudo que passa pelo widget de alerta: doações em Pix e, com a conta conectada, [sub, bits e raid da Twitch e da Kick](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs). ## Configurar 1. Em **Integrações → Stream Deck e controle remoto**, clique em **Gerar token**. Ele pede sua senha e mostra o token uma única vez. 2. No Stream Deck, instale um plugin de requisição HTTP (o "Web Requests" serve). 3. Em cada tecla: método **POST**, a URL da ação (o painel lista todas, com botão de copiar) e o header `Authorization: Bearer SEU_TOKEN`. Uma tecla por ação. Qualquer coisa que faça um POST funciona: atalho de teclado, automação no celular, macro. ## Segurança O token é próprio do controle remoto. Ele **não acessa saldo, saques nem cobranças**, e não é a chave da API. Se vazar, revogue no painel e gere outro; o antigo para de funcionar na hora. ## Se esquecer pausado Acontece. Por isso o painel mostra um aviso "Pelo controle remoto: alertas pausados" com um botão **Normalizar**, que volta tudo ao normal. E o estado é por conta: vale para todos os seus widgets de alerta, em qualquer cena. ## Leia também - [Sub, bits e raid da Twitch e da Kick no mesmo alerta](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs) - [Maratona (subathon) com Pix, subs e bits](/blog/maratona-subathon-com-pix-como-configurar) - [Como configurar o widget de alerta no OBS](/blog/como-receber-pix-na-live-guia-streamer) --- # Doação Pix na Twitch: por que streamers preferem Pix aos bits (e como configurar) Fonte: https://botapix.com/blog/doacao-pix-na-twitch-pix-ou-bits Todo streamer brasileiro de Twitch descobre a mesma coisa no primeiro pagamento: **o que a audiência gastou não é o que chegou**. Bits, subs e afins passam pela loja da Twitch, pela taxa da Twitch, pelo câmbio do dólar e por um calendário de repasse — e cada etapa morde um pedaço. Não é por acaso que quase toda live BR tem um link de doação Pix fixado no chat. Este post coloca a matemática lado a lado e mostra como configurar o Pix sem ferir as regras da Twitch. ## Quanto fica no caminho: bits vs Pix Os números públicos, aproximados (a Twitch não publica uma tabela única e os preços de bits variam por pacote e promoção): | | Bits | Sub (nível 1) | Doação Pix | |---|---|---|---| | Quem processa | Twitch | Twitch | Plataforma de Pix | | Fica com a plataforma | ~30% do que o viewer pagou | ~50% | ~3% | | Moeda do repasse | Dólar (câmbio + IOF por sua conta) | Dólar | Real, direto | | Quando você recebe | Ciclo mensal, com mínimo de saque | Ciclo mensal | Confirmação em segundos, saque em horas | Traduzindo para R$ 1.000 gastos pela sua audiência: - **Via bits:** na casa de **R$ 700** chegam até você — antes do câmbio e do prazo - **Via doação Pix (BotaPix):** taxa de 3% → **R$ 970** no seu saldo, na hora (a tarifa de saque de 1,5% incide quando você transfere para o banco — a conta completa está no [comparativo de plataformas](/blog/botapix-vs-alternativas-comparativo-2026)) A diferença não é marginal. Para um canal que movimenta R$ 2.000/mês em apoio da audiência, são **centenas de reais por mês** que mudam de destino dependendo do botão que o viewer aperta. ## Então bits é golpe? Não — é outra coisa Sendo justo com a Twitch: bits e subs não são só pagamento, são **parte do produto**. Sub dá emote, badge e chat sem anúncio; bits têm animação no chat e contam para hype train. Isso tem valor real de comunidade, e parte da audiência vai usar de qualquer jeito — principalmente quem tem Prime. A estratégia que os canais grandes usam não é "ou um ou outro": - **Sub/bits** para quem quer os benefícios dentro da Twitch - **Pix** como caminho principal para quem quer que o apoio **chegue quase inteiro** — e para doação por impulso, que é onde o alerta com TTS e o QR Code na tela fazem diferença Vale deixar isso explícito para o seu público: um painel "prefere que o apoio chegue inteiro? usa o Pix" converte melhor do que o link solto. ## Pode isso, Arnaldo? (regras da Twitch) Pode. Doação externa é prática universal na plataforma — os próprios "tip jar" gringos (StreamElements, StreamLabs) funcionam assim há uma década. O que as diretrizes da Twitch esperam de você: - O link de doação é seu e a transação acontece **fora** da Twitch — a responsabilidade pela entrega é sua e da plataforma de pagamento - Não dá para usar doação externa para vender o que é produto da Twitch (ex.: prometer benefício de sub pago por fora) - Imposto de renda sobre doações recebidas continua existindo, com ou sem Twitch no meio ## Como configurar o Pix na sua live da Twitch O fluxo completo tem [guia próprio para iniciante](/blog/como-receber-pix-na-live-guia-streamer); a versão curta: 1. **Crie a conta** numa plataforma de Pix para live ([BotaPix](/register), por exemplo) e cadastre a chave onde os saques vão cair — ela nunca aparece para quem doa 2. **Adicione o widget de alerta no OBS** como fonte de Navegador — doação dispara alerta com nome, valor, mensagem e TTS por cima do gameplay 3. **Fixe o link** da sua página de doação: comando `!pix` no chat (Nightbot/StreamElements), painel na descrição do canal e o QR Code de tela para quem assiste do celular 4. **Teste antes de ir ao ar** com o disparo de alerta de teste Do lado do viewer, a fricção é mínima — e isso importa mais do que parece: bits exigem comprar pacote antecipado em dólar; **o Pix a pessoa já tem no celular**, e doa R$ 2 no impulso do momento. ## Recapitulando - De cada R$ 1.000 da audiência, bits entregam na casa de R$ 700 (em dólar, semanas depois); Pix entrega ~R$ 970 (em reais, na hora) - Bits e subs continuam valendo pelos benefícios dentro da Twitch — o jogo certo é oferecer os dois - Doação externa é permitida e padrão na plataforma - A configuração é a mesma de qualquer live com Pix: widget no OBS + link no chat Quer começar? [Crie sua conta grátis](/register) ou veja primeiro o [comparativo entre as plataformas brasileiras](/blog/botapix-vs-alternativas-comparativo-2026). --- # Pix que roda vídeo na live: como funciona o media request (e como configurar) Fonte: https://botapix.com/blog/pix-que-roda-video-na-live-media-request Você já viu isso em live grande: alguém doa e, junto com o alerta, **um vídeo do YouTube toca na tela** — um meme, um clipe, uma música. É o *media request* (ou media share), e é um dos recursos que mais aumenta o valor médio das doações: o doador não está só apoiando, está **comprando um momento na sua transmissão**. Até pouco tempo, isso era coisa de plataforma gringa. Agora existe no BotaPix, funcionando com Pix: o doador cola um link do YouTube na hora de doar, você modera, e o vídeo roda direto no widget do OBS. Este post explica como funciona por dentro — preço por segundo, fila de moderação, banimento — e como configurar do zero. ## Como funciona pra quem doa Na sua página de doação (`botapix.com/s/seunome`), quando o media request está ativo, aparece um campo para colar um **link de vídeo do YouTube**. Vale qualquer formato que as pessoas realmente usam: `youtube.com/watch?v=`, `youtu.be/`, link de Shorts e até link de vídeo ao vivo. O doador também pode escolher **a partir de que segundo** o vídeo começa — útil para pular direto para o momento do meme. A parte importante: **o valor da doação compra tempo de exibição**. Você define o preço por segundo; a doação define quantos segundos tocam. ## Como funciona pra você: preço por segundo Você controla três números: | Configuração | O que faz | Limites | |---|---|---| | **Preço por segundo** | Quanto custa cada segundo de vídeo | R$ 0,01 a R$ 10,00 | | **Mínimo de segundos** | Duração mínima de um pedido | 5 a 300s | | **Máximo de segundos** | Teto de duração por pedido | 10 a 600s | Um exemplo concreto: preço de **R$ 0,10/segundo**, mínimo de 10s e máximo de 120s. - Doação de R$ 5 → toca **50 segundos** - Doação de R$ 20 → tocaria 200s, mas trava no teto → **120 segundos** - Doação abaixo de R$ 1 (o mínimo de 10s × R$ 0,10) → o pedido nem é aceito Tudo isso é calculado **no servidor**, não no navegador de quem doa — ninguém consegue "hackear" mais segundos do que pagou. > **Dica de calibragem:** comece com preço baixo (R$ 0,05–0,10/s) e teto curto (60–90s). É melhor ter vários pedidos baratos animando o chat do que um vídeo de 10 minutos travando a live. Suba o preço conforme a demanda aparecer. ## A fila de moderação (a parte que salva sua live) Vídeo escolhido por desconhecido na internet + sua tela ao vivo = receita para desastre, se não houver controle. Por isso o fluxo tem moderação embutida: 1. O doador paga e o pedido cai na **fila de aprovação** do seu painel 2. Você vê o vídeo, quem pediu e quantos segundos comprou 3. **Aprovar** → entra na fila de exibição do widget 4. **Rejeitar** → não toca (o valor fica como doação normal) 5. **Rejeitar e banir** → não toca e o vídeo entra na sua lista de banidos — pedidos futuros com o mesmo vídeo são recusados automaticamente, antes mesmo do pagamento A lista de banidos guarda até 200 vídeos, e você pode desbanir pelo painel quando quiser. E se um vídeo aprovado começar a tocar e você mudar de ideia, tem o botão de **pular** — o vídeo some da tela na hora. Vídeo que o YouTube não deixa tocar fora do site (removido, privado, sem permissão de embed) é recusado na própria página de doação, antes do pagamento. Se mesmo assim o player falhar na hora, o pedido volta para o painel marcado como **não tocou**, com a opção de tentar de novo ou descartar — nada some em silêncio. O tempo comprado só começa a contar quando o vídeo de fato está rodando: o carregamento não come os segundos pagos. Prefere confiança total na sua comunidade? Dá para **desligar a aprovação manual** e todo pedido pago vai direto para fila. Recomendamos manter a moderação ligada pelo menos nas primeiras semanas. ## E os direitos autorais? Ponto que ninguém te conta nos tutoriais: o vídeo toca **na sua transmissão**, então as regras de conteúdo de onde você transmite (Twitch, YouTube, Kick) valem para ele. Música com copyright pode gerar strike ou mute no VOD, exatamente como se você mesmo tivesse tocado. Três cuidados práticos: - Use a moderação para filtrar clipe de música comercial se a sua plataforma é rígida com DMCA - O controle de **volume** do widget é seu — vídeo não precisa esmagar o áudio do jogo - Bloqueou um vídeo problemático uma vez? Use o "rejeitar e banir" para ele não voltar ## Configurando no OBS, passo a passo Se você já usa o widget de alerta do BotaPix, o de media é igual ([guia completo de configuração aqui](/blog/como-receber-pix-na-live-guia-streamer)): 1. No painel, ative o widget de **Media** e ajuste preço, mínimo, máximo e volume 2. Copie o **Browser Source URL** do widget (é secreto — não mostre na live) 3. No OBS, adicione uma fonte **Navegador**, cole a URL, 1920×1080 4. Posicione a fonte na cena — o vídeo aparece nesse espaço quando um pedido tocar 5. Dispare um pedido de teste antes de ir ao ar A fila anda sozinha: acabou um vídeo, entra o próximo aprovado. Com a moderação ligada, deixe a aba **Vídeos** do painel aberta durante a live — é lá que os pedidos aguardando aprovação aparecem. ## Quem mais tem isso? No mercado brasileiro de Pix em live, media request é raridade — a maioria das plataformas para em alerta + TTS. Na prática, quem oferece algo comparável é o StreamElements (que é gringo e não é Pix). Se esse recurso importa para o seu formato de live, é um bom critério de desempate na [comparação entre plataformas](/blog/botapix-vs-alternativas-comparativo-2026). ## Recapitulando - O doador cola um link do YouTube e o valor da doação compra segundos de exibição - Você define preço por segundo, duração mínima e máxima - Fila de moderação com aprovar / rejeitar / **banir** — e botão de pular durante a exibição - O vídeo toca no widget do OBS, junto do alerta de doação de sempre - Direitos autorais na transmissão continuam sendo responsabilidade de quem transmite — use a moderação Quer testar? [Crie sua conta](/register), ative o widget de Media e faça um pedido de teste na sua própria página. Se ainda não recebe Pix na live, comece pelo [guia do streamer iniciante](/blog/como-receber-pix-na-live-guia-streamer). --- # Assinaturas via Pix Automático: como cobrar todo mês sem o cliente fazer nada Fonte: https://botapix.com/blog/assinaturas-pix-automatico-no-botapix Cobrança recorrente no Brasil sempre dependeu de cartão de crédito. Quem não tinha cartão — ou não queria deixar o número salvo num site — ficava de fora. E quem recebia tinha que lidar com taxa de cartão, recusa por limite e chargeback. O **Pix Automático** resolve isso. O cliente autoriza **uma única vez** no app do banco dele, e a partir daí o valor é debitado **todo mês automaticamente** — sem cartão, sem ele precisar abrir nada, sem pagar de novo. É a mesma ideia da assinatura no cartão, mas rodando sobre o Pix. No BotaPix isso já está disponível. Este post explica o que é, como o dinheiro chega até você e como ativar — pela dashboard ou via API. ## O que é o Pix Automático (e o que ele não é) O Pix Automático é um recurso do próprio Banco Central, lançado para permitir **débitos recorrentes autorizados**. Não confunda com: - **Pix comum:** o cliente paga uma vez, na hora. - **Pix agendado:** o cliente agenda *um* pagamento futuro, único. - **Pix Automático:** o cliente autoriza um **mandato** — uma permissão para você cobrar de forma recorrente, dentro de um valor combinado. A diferença que mais importa: depois de autorizado, **o cliente não faz mais nada**. Ele não recebe um QR novo todo mês, não precisa abrir o banco, não precisa lembrar de pagar. O débito acontece sozinho. E ele continua no controle: pode cancelar a assinatura a qualquer momento, direto no app do banco — é uma garantia do Pix Automático. ## Por que isso é bom pra quem recebe Se você cobra mensalidade — uma comunidade, um clube de assinatura, um SaaS, apoio recorrente de streamer — o Pix Automático muda três coisas: - **Menos cancelamento por esquecimento.** No modelo "manda o Pix todo mês", muita gente esquece e some. Aqui o débito é automático. - **Sem taxa de cartão e sem chargeback de cartão.** É Pix: liquidação direta, sem a estrutura de cartão por trás. - **Alcança quem não tem cartão.** Qualquer conta com Pix consegue assinar. ## O fluxo, do começo ao fim Independente de você usar a dashboard ou a API, por baixo acontece sempre a mesma coisa. Existem **duas camadas** — vale entender a diferença, porque é onde mora a confusão: 1. **O mandato (a autorização):** o cliente aprova uma vez. Isso só dá *permissão*. Não move dinheiro. 2. **A cobrança do ciclo (o débito):** a cada mês, o BotaPix emite a cobrança vinculada àquela autorização. É isso que efetivamente debita o cliente. O mandato autoriza; a cobrança do mês cobra. Passo a passo: 1. **Você cria a assinatura** com o valor mensal e o CPF do cliente. 2. O cliente recebe um **Pix Copia e Cola de autorização** (ou QR Code). 3. Ele cola no app do banco, na opção **Pix Copia e Cola**, e o banco mostra a tela de **autorizar uma assinatura** — não é um pagamento avulso, ele vê "débito mensal de R$ X". 4. Ele autoriza. A assinatura vira **ativa**. 5. A cada mês, o BotaPix cobra o ciclo automaticamente e o cliente é debitado no vencimento. 6. **O dinheiro cai no seu saldo** já líquido — exatamente como qualquer outro recebimento Pix. Esse último ponto é importante: para o seu lado, **o ciclo liquidado é um recebimento normal**. Ele aparece na sua lista de pagamentos e entra no seu saldo disponível para saque, igual a uma cobrança avulsa. Se você tem webhook configurado, recebe o mesmo evento `payment.confirmed` de sempre. > **Sobre o primeiro débito:** ele não acontece no mesmo segundo da autorização. O Pix Automático exige alguns dias de antecedência entre a cobrança e o vencimento. Então o primeiro débito sai nos primeiros dias após a autorização — e, a partir daí, todo mês. ## Ativando pela dashboard (sem código) Se você recebe pela sua página pública do BotaPix (`/s/seu-usuario`), é direto: 1. No dashboard, em **Assinaturas**, ative o aceite de assinaturas. 2. Sua página pública passa a oferecer a opção de assinar. 3. O apoiador escolhe o valor, recebe o QR de autorização e aprova no banco. 4. Pronto — você acompanha as assinaturas ativas no painel, e cada ciclo cai no seu saldo. O cancelamento, lembrando, é controlado pelo cliente no app do banco dele — por isso o painel é de acompanhamento, não de gestão manual do débito. ## Ativando via API (no seu próprio checkout) Se você integra o BotaPix no seu site, é um endpoint só. Crie a assinatura: ```php $response = Http::withToken(env('BOTAPIX_API_KEY')) ->post('https://botapix.com/api/v1/subscriptions', [ 'amount' => 2500, // centavos = R$ 25,00/mês 'customer' => [ 'name' => 'João Apoiador', 'document' => '12345678909', // CPF — exigência do Pix Automático ], 'description' => 'Plano mensal', 'external_reference' => 'assinante_42', ]); $subscription = $response->json('data'); ``` A resposta traz o copia-e-cola de autorização: ```json { "data": { "id": 1, "reference": "RN1234567820240115abcdefghijk", "status": "pending_auth", "amount": 2500, "authorization_pix_copia_cola": "00020126...", "...": "..." } } ``` Mostre o `authorization_pix_copia_cola` para o cliente (como QR ou texto). Quando ele autoriza no banco, a assinatura vira `active` e os ciclos passam a ser cobrados automaticamente. Para acompanhar, consulte ou liste: ```php // Uma assinatura (por id ou reference) Http::withToken($key)->get("https://botapix.com/api/v1/subscriptions/{$id}"); // Todas, com filtro de status Http::withToken($key)->get('https://botapix.com/api/v1/subscriptions?status=active'); ``` E se precisar cancelar pelo seu lado: ```php Http::withToken($key)->delete("https://botapix.com/api/v1/subscriptions/{$id}"); ``` A cada ciclo liquidado, se você tiver webhook configurado, recebe o mesmo `payment.confirmed` das cobranças avulsas — com o `reference` daquele recebimento, `source` igual a `subscription` e o `subscription_id` da assinatura. Ou seja: **você não precisa de código novo para reconciliar assinatura**; é o mesmo evento que você já trata. Para acompanhar a autorização e o cancelamento, a assinatura também envia os eventos `subscription.activated`, `subscription.rejected` e `subscription.canceled`. Os payloads estão na [documentação de eventos](/docs/webhooks/eventos#eventos-de-assinatura). ## Os estados de uma assinatura | Status | O que significa | |---|---| | `pending_auth` | Criada, esperando o cliente autorizar no banco. | | `active` | Autorizada. Os ciclos são cobrados automaticamente. | | `canceled` | Cancelada — não cobra os próximos ciclos. | | `rejected` | O cliente recusou a autorização. | ## TL;DR - Pix Automático = cobrança recorrente sobre o Pix: o cliente **autoriza uma vez** e o resto é automático. - Sem cartão, sem chargeback de cartão, alcança quem não tem cartão. - Para o seu lado, **cada ciclo é um recebimento normal** — cai no saldo, aparece nos pagamentos, dispara `payment.confirmed`. - Ative pela **dashboard** (sem código) ou via **API** (um `POST /api/v1/subscriptions`). - O cliente cancela quando quiser, no próprio banco. A documentação completa está em [Assinaturas → Criar](/docs/assinaturas/criar). Para testar, [crie sua conta](/register) — o ambiente fica pronto em minutos. --- # Como colocar live pix na sua live: Twitch, Kick, YouTube e OBS (2026) Fonte: https://botapix.com/blog/como-receber-pix-na-live-guia-streamer A receita mais comum de quem faz live no Brasil hoje não vem de subs ou de programas de afiliado — vem de **doações via Pix**, o que todo mundo chama de **live pix**. É barato para quem doa, instantâneo para quem recebe e dispensa cartão de crédito. Mas tem um problema: a maioria dos tutoriais sobre isso é em vídeo. Se você quer entender o fluxo inteiro antes de gastar 40 minutos assistindo, este post é para você. Ele cobre o OBS e o que muda na **Twitch**, na **Kick** e no **YouTube**. ## O que é live pix "Live pix" virou o nome genérico de **doação via Pix durante a live com alerta na tela**: o espectador paga um Pix, o valor e a mensagem aparecem no meio da transmissão e o streamer agradece na hora. O nome veio de uma das primeiras plataformas a fazer isso, mas hoje várias fazem a mesma coisa, cada uma com a sua taxa. O fluxo é sempre o mesmo: 1. O espectador abre a sua página de doação (ou escaneia o QR Code na tela) e paga um Pix. 2. A plataforma confirma o pagamento em segundos. 3. O alerta aparece no OBS, com voz lendo a mensagem se você quiser. 4. O dinheiro fica no seu saldo na plataforma, e você saca para a sua chave Pix. ## O que você precisa antes de começar Independente da plataforma escolhida, todo streamer brasileiro precisa de **três coisas** para receber Pix na live: 1. **Uma conta bancária ou de fintech** com chave Pix cadastrada (CPF, e-mail, telefone ou aleatória). 2. **O OBS Studio** instalado no PC que faz a transmissão (ou Streamlabs Desktop, que é o OBS com algumas features extras). 3. **Uma plataforma intermediária** que recebe o Pix, dispara o alerta na sua tela e repassa para sua conta. Sobre o **terceiro item**: você até consegue só colar um QR Code estático no canto da tela, mas perde o alerta animado, o TTS, o ranking de doadores e a página de pagamento personalizada. A plataforma resolve isso. ## Por que não usar a sua chave Pix direto Tecnicamente, dá. Você gera um QR Code da sua chave em qualquer banco, baixa a imagem, coloca como overlay no OBS, e qualquer doação cai direto. Três problemas: - **Exposição da chave pessoal:** se você usa CPF, telefone ou e-mail como chave, esse dado fica visível na tela e no comprovante de quem doa. CPF é privado por lei. - **Sem alerta animado:** o doador paga e fica esperando você ver. Você vai notar quando olhar a notificação do banco — pode ser daqui a 5 minutos. Engajamento zero. - **Sem mensagem do doador:** não dá para ler o que ele escreveu junto. Por isso existem as plataformas. Elas dão um QR Code intermediário, recebem por você e disparam o alerta visual na hora. ## As plataformas brasileiras de live pix Hoje existem várias opções no mercado, todas funcionam mais ou menos igual. As diferenças estão na **taxa**, em **quanto tempo o dinheiro fica retido**, e nos **recursos extras** (TTS com IA, ranking, metas, integração com StreamLabs). As principais são: - **LivePix** — a mais conhecida, fundada antes do Pix virar mainstream. Tem QR Code, alerta, página de doação e voz por texto. Cobra taxa por transação. - **Tipa.ai** — bem simples, tem doação avulsa e assinatura mensal. - **AlertPix** — entrada mais recente, foca em personalização visual do alerta. - **BotaPix** — o nosso. 3% por transação, sem mensalidade, API documentada, widgets prontos, TTS com IA. A escolha entre elas é menos sobre "qual é a melhor" e mais sobre **qual taxa cabe no seu volume** e **se você precisa de algum recurso específico**. Cobrimos isso em detalhe em [BotaPix vs alternativas](/blog/botapix-vs-alternativas-comparativo-2026). Para o resto deste guia, vamos usar BotaPix como exemplo porque é o que conhecemos por dentro — mas o fluxo é equivalente em qualquer plataforma. ## Passo 1: criar a conta e cadastrar sua chave Pix [Cadastre-se no BotaPix](/register) — leva menos de um minuto, com a conta do Google ou com e-mail e senha. Você informa nome completo e CPF (ou CNPJ, se for PJ). Depois do cadastro, você cai no painel. Vá em **Configurações → Chave Pix** e cadastre a chave onde os saques vão cair. Pode ser CPF, e-mail, telefone ou chave aleatória — qualquer uma serve, **mas tem que pertencer a você** (validamos a titularidade no momento do saque). > **Atenção:** a chave Pix que você cadastra aqui é só para **saques**. Quem doa não vê essa chave em momento nenhum. ## Passo 2: montar sua página de doação Streamers no BotaPix têm uma página própria em **botapix.com/s/seunome**. É para onde o público vai para doar. Na primeira entrada como streamer, o painel te leva pela configuração da página: - **Nome de usuário** (a URL fica `/s/seunome`) - **Foto de perfil** - **Wallpaper de fundo** (opcional) - **Cor de destaque** (combina com o tema do seu canal) - **Descrição** (o que aparece embaixo do seu nome) Depois, tudo isso fica em **Live → Minha Página**. Pegue o link da página e mantenha sempre à mão — é o que você vai divulgar no chat da live. ## Passo 3: como colocar o live pix no OBS Agora a parte do OBS. No painel, vá em **Live → Minha Página**, abra o widget de **Alerta** e copie a URL dele. É um link tipo: ``` https://botapix.com/widget/abc123xyz... ``` Esse link é **secreto** — quem tiver acesso a ele consegue disparar alertas falsos na sua live. Não compartilhe. No OBS Studio: 1. Adicione uma fonte do tipo **Navegador** (ou **Browser** se estiver em inglês) 2. Cole a URL no campo **URL** 3. Use a largura e a altura que aparecem embaixo da URL no painel (**Tamanho no OBS**) 4. Marque **Atualizar navegador quando a cena ficar ativa** 5. Clique em OK Pronto. O widget fica invisível até alguém doar. Quando uma doação cai, o alerta aparece sobre o gameplay com: - Nome do doador (ou "Anônimo" se ele preferir) - Valor - Mensagem - Voz lendo a mensagem com TTS, se você ativou O mesmo vale para os outros widgets (QR Code, ranking, meta, histórico): cada um tem a sua URL e vira uma fonte de Navegador no OBS. No Streamlabs Desktop o caminho é igual: **Fonte → Navegador**. ## Passo 4: testar antes de ir ao ar Antes de transmitir para valer, teste o alerta. Em **Live → Minha Página**, no widget de Alerta, o botão **Testar alerta** dispara uma doação de mentira na sua cena. Confirme: - O alerta aparece em cima do gameplay, não atrás - O TTS está com volume audível (mas não esmagando o áudio do jogo) - A duração do alerta é suficiente para você reagir Se algo está estranho, ajuste nas configurações do widget e teste de novo. ## Live pix na Twitch A Twitch não tem campo para Pix, então o caminho é levar o público até a sua página: - **Painel do canal:** em **Sobre → Editar painéis**, crie um painel com o texto "Apoie a live com Pix" e o link `botapix.com/s/seunome`. Fica visível embaixo do player o tempo todo. - **Comando de chat:** no Nightbot ou no StreamElements, crie um `!pix` que responde com o link. - **QR Code na tela:** o widget de QR Code vira uma fonte no OBS. Quem assiste pelo celular escaneia direto. - **Sub, bits e raid no mesmo alerta:** em **Live → Integrações**, conecte a Twitch e o widget que você já tem passa a mostrar esses eventos também ([como funciona](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs)). O Pix não passa pela Twitch: o dinheiro vai para o seu saldo no BotaPix, sem a retenção dos bits e subs. Comparamos os dois em [Pix ou bits na Twitch](/blog/doacao-pix-na-twitch-pix-ou-bits). ## Live pix na Kick Na Kick o processo é o mesmo: - **Bio e links do canal:** coloque o link da sua página de doação. - **Comando de chat:** um bot de chat da Kick (como o Botrix) responde `!pix` com o link. - **QR Code e alerta no OBS:** iguais aos da Twitch, porque o alerta roda no OBS, não na plataforma. - **Subs da Kick no alerta:** em **Live → Integrações**, conecte a Kick para os subs aparecerem no mesmo alerta do Pix. ## Live pix no YouTube No YouTube, o link vai em dois lugares: - **Descrição da live:** "Apoie com Pix: botapix.com/s/seunome". - **Mensagem fixada no chat:** fixe o link no começo da transmissão. O alerta e o QR Code continuam no OBS, iguais aos das outras plataformas. O Pix é uma alternativa ao Super Chat sem a fatia que o YouTube retém. ## Passo 5: divulgar o link na live Quando a transmissão começar, jogue o link no chat: `botapix.com/s/seunome`. Repita a cada 15-20 minutos enquanto estiver ativo, sem ser chato. O comando `!pix` e o QR Code na tela fazem isso por você. ## Quanto custa: a taxa do live pix Toda plataforma cobra uma taxa por doação, e algumas cobram também para sacar. No BotaPix: - **3% por doação**, sem mensalidade nem adesão - **Saque a partir de R$ 10,00**, com tarifa de 1,5% (mínimo R$ 0,50) Uma doação de R$ 10,00 deixa R$ 9,70 no seu saldo. A tabela completa está em [Taxas](/taxas), e a comparação com as outras plataformas em [comparativo de taxas](/blog/botapix-vs-alternativas-comparativo-2026). ## E os saques? Tudo que você recebe vai para o saldo da sua conta no BotaPix. Em **Ganhos → Saques** você pede transferência para sua chave Pix cadastrada. - **A partir de R$ 10,00** — sem mínimo absurdo - **Saques até R$ 500** são liberados automaticamente, sem aprovação manual - Cada saque passa por uma **verificação de segurança** e é processado em poucas horas — é o que te protege contra contestações indevidas - **Tarifa de saque de 1,5%** (mínimo R$ 0,50), deduzida do valor transferido — cobre o custo de processamento do Pix - **24/7** — peça quando quiser, não tem horário comercial Outras plataformas têm regras diferentes; veja o [comparativo](/blog/botapix-vs-alternativas-comparativo-2026) se quiser entender. ## Erros comuns no primeiro dia Em ordem de frequência: 1. **Alerta não aparece** — geralmente é a cena no OBS que não tem a fonte do widget. Confirme que a fonte de Navegador está visível na cena ativa. 2. **TTS não toca** — você precisa autorizar áudio no navegador interno do OBS. Reinicie a fonte com botão direito → Recarregar. 3. **QR Code lê o seu próprio Pix em vez do BotaPix** — você colou seu QR Code pessoal em vez do widget. Confira a URL. 4. **Doador disse que pagou mas não viu o alerta** — a confirmação do Pix leva alguns segundos. Confirme em **Ganhos → Pagamentos** se o pagamento entrou. ## Perguntas frequentes ### Live pix tem taxa? Tem: toda plataforma cobra uma porcentagem de cada doação. No BotaPix são 3% por doação, sem mensalidade; o valor de cada concorrente está no [comparativo](/blog/botapix-vs-alternativas-comparativo-2026). ### Preciso de CNPJ para receber live pix? Não. Dá para receber como pessoa física, com CPF. Quem tem CNPJ também pode se cadastrar como PJ. ### Funciona na Kick e no YouTube, não só na Twitch? Sim. O alerta roda no OBS, então funciona em qualquer plataforma para a qual você transmite pelo OBS: Twitch, Kick, YouTube e outras. ### Quem doa precisa ter conta? Não. O espectador abre a sua página, digita o valor e a mensagem e paga o Pix no app do banco. ### Minha chave Pix aparece para quem doa? Não. Quem doa paga para o BotaPix, e você saca para a sua chave depois. Seu CPF, telefone ou e-mail não aparecem na tela nem no comprovante. ## O que mais dá pra fazer depois do básico Com página, chave e alerta no ar, o resto é engajamento. Tudo abaixo já existe no BotaPix e cada um tem um guia próprio: - [Sub, bits e raid da Twitch e da Kick no mesmo alerta do Pix](/blog/alertas-de-sub-bits-e-raid-twitch-e-kick-no-obs): conecta a conta e o widget que você já tem passa a mostrar os eventos da plataforma. - [Maratona (subathon)](/blog/maratona-subathon-com-pix-como-configurar): cronômetro que ganha tempo com cada Pix, sub ou bits. - [Enquetes com Pix](/blog/enquetes-com-pix-na-live): a audiência decide o que rola na live votando com Pix. - [Recompensas](/blog/recompensas-para-quem-doa-ou-assina): link do Discord, código ou conteúdo secreto para quem doa ou assina. - [Stream Deck](/blog/stream-deck-pausar-pular-e-silenciar-alertas): pausar, pular e silenciar os alertas com uma tecla. - [App para Android](/blog/app-botapix-android-mapa-irl-ao-vivo): saldo, saque e doações pelo celular, e o mapa IRL ao vivo no OBS. ## Pra recapitular 1. Cadastre-se na plataforma escolhida 2. Cadastre sua chave Pix (para receber saques) 3. Monte sua página de doação 4. Adicione o widget de alerta no OBS como fonte de Navegador 5. Teste antes de ir ao ar 6. Coloque o link no painel da Twitch, na bio da Kick ou na descrição do YouTube, e divulgue no chat Resto vem com a prática. Quanto mais você usa, mais entende o que funciona para sua audiência — tempo de alerta, voz do TTS, posicionamento na tela. Ajuste conforme for percebendo o que engaja. Se for usar BotaPix, [crie a conta aqui](/register). Se quiser ver outras opções primeiro, dê uma olhada no [comparativo de plataformas](/blog/botapix-vs-alternativas-comparativo-2026). --- # LivePix, Tipa.ai ou BotaPix? Comparativo de taxas de Pix em live (2026) Fonte: https://botapix.com/blog/botapix-vs-alternativas-comparativo-2026 Tem várias plataformas brasileiras para receber Pix em live hoje. A diferença entre elas é menos sobre "quem tem o widget mais bonito" e mais sobre **quanto cada R$ 1,00 doado vira na sua conta**. Este post compara as três opções mais usadas para **streamer de volume médio** com dados públicos de taxa e saque. ## Resumo da tabela | Plataforma | Taxa por doação | Taxa de saque | |---|---|---| | **BotaPix** | **3,00%** | 1,5% (mín. R$ 0,50) | | **Tipa.ai** | 3,99% | (não publicada na página de taxas) | | **LivePix** | 5,00% | 3 grátis/mês, depois R$ 0,50 | *Última verificação: junho/2026. Confirme as taxas atuais na página oficial de cada plataforma antes de decidir.* ## Quanto isso vira na prática A diferença de 2 pontos percentuais parece pequena. Mas em volume médio de streamer (R$ 2.000/mês em doações), o impacto é real: | Plataforma | Volume recebido | Você fica com | |---|---|---| | **BotaPix** | R$ 2.000 | **R$ 1.940** | | Tipa.ai | R$ 2.000 | R$ 1.920 | | LivePix | R$ 2.000 | R$ 1.900 | A diferença entre 3% e 5% é **R$ 40 a mais por mês** no seu bolso. Em um ano, são **R$ 480** que ficam com você ao invés de virar taxa. Em um canal com R$ 20k/mês de volume, são **R$ 4.800/ano**. A escolha não é só taxa — mas a taxa importa muito mais do que parece. ## Onde cada plataforma se destaca ### LivePix A mais conhecida do mercado. Praticamente todo tutorial de "como receber Pix na live" no YouTube usa LivePix como referência. Tem ferramentas de assinatura mensal, ranking, metas, vaquinha colaborativa. **Forte em:** reconhecimento de marca, ecossistema grande, comunidade ativa de tutoriais. **Fraco em:** taxa de 5% é a mais alta entre as plataformas comparadas. Em volumes médios e altos, isso pesa. ### Tipa.ai Foco em simplicidade. O doador não precisa criar conta nem cadastrar nada — só escanear, pagar e mandar mensagem. **Forte em:** UX simples pro doador, sistema nativo de assinatura mensal por Pix. **Fraco em:** taxa de 3,99% fica em um meio termo — nem o mais barato, nem o mais completo. A página de taxas não publica condições de saque com clareza. ### BotaPix A nossa. **3% por transação, sem mensalidade.** API REST documentada ([/docs](/docs)), webhooks assinados com HMAC-SHA256, widgets prontos pro OBS (alerta, ranking, meta, QR Code, maratona, enquete, Media Share). O alerta pode ler toda doação em voz alta sem custo extra (três vozes neurais em português) e quem doa pode escolher uma voz de IA, inclusive de personagem. Tem assinatura mensal por Pix Automático, vaquinha, alertas de sub, bits e raid da Twitch e da Kick e integração com o StreamLabs. **Forte em:** menor taxa entre as três plataformas comparadas, API pública aberta (útil pra quem integra em sistemas próprios), documentação completa, saldo disponível assim que o pagamento é confirmado. **Fraco em:** plataforma mais nova — comunidade ainda em crescimento, menos tutoriais de terceiros que outras opções. ## Como escolher Não tem "melhor para todo mundo". Em ordem prática: 1. **Se você está começando** e ainda não recebe muito (até R$ 500/mês) — vai na plataforma que **te dá menos atrito para configurar**. A taxa em valores pequenos é irrelevante; o que importa é você ir ao ar e começar a gerar volume. 2. **Se você já tem volume estável** (R$ 1k-10k/mês) — a taxa começa a pesar. **BotaPix tem a menor taxa** entre as três aqui. 3. **Se você é dev ou tem um produto próprio** onde quer integrar Pix — vai na plataforma com **API documentada**. BotaPix nasceu com isso como prioridade; veja a [documentação pública](/docs). 4. **Se você precisa de assinatura mensal por Pix** — Tipa.ai e LivePix têm esse fluxo nativo. No BotaPix é o [Pix Automático](/blog/assinaturas-pix-automatico-no-botapix): o apoiador autoriza uma vez no app do banco e o débito sai todo mês, por R$ 3,50 + 3% por cobrança. ## Recursos extras a checar Além da taxa, vale comparar: - **Retenção de saldo após confirmação** — algumas plataformas seguram o saldo por dias antes de liberar para saque. No BotaPix o valor entra no saldo assim que o pagamento é confirmado; você pode pedir saque a qualquer momento. - **Limite mínimo de saque** — quanto menor, melhor para quem recebe pouco. BotaPix libera **a partir de R$ 10,00**. - **Tempo de processamento do saque** — BotaPix libera **automaticamente até R$ 500** (sem aprovação manual); acima disso tem aprovação manual. Todo saque passa por uma verificação de segurança e é processado em poucas horas — é o que protege contra contestações indevidas. - **TTS (voz lendo a mensagem)** — todas as principais oferecem; verifique quais vozes PT-BR, a qualidade e se tem custo extra. No BotaPix, a leitura de toda doação não custa nada a mais. - **Integração com StreamLabs/StreamElements** — útil se você já usa essas ferramentas para outros alertas. ## Por que comparativos existentes geralmente são tendenciosos A maioria dos posts de "alternativas ao LivePix" é escrito por **uma das alternativas**. Esse aqui não foge dessa regra — somos BotaPix. O que tentamos fazer aqui: dados objetivos (taxas vêm das páginas oficiais de cada plataforma), vantagens e fraquezas balanceadas, sem afirmar que somos os melhores em tudo. Verifique sempre antes de decidir. Cada plataforma publica suas taxas no próprio site — basta procurar pela página de "Taxas" ou "Preços". A BotaPix mantém o detalhe completo na [documentação pública](/docs). ## Próximo passo Se você se decidiu pelo BotaPix, [crie conta aqui](/register) — leva 1 minuto. Se ainda está em dúvida, leia o [guia de como receber Pix na live](/blog/como-receber-pix-na-live-guia-streamer) — o fluxo é parecido em qualquer plataforma, e você pode mudar de ideia depois. --- # MED do Pix: o que é, como funciona e o que acontece com seu saldo se um cliente abrir uma disputa Fonte: https://botapix.com/blog/med-do-pix-o-que-e-e-como-protege-vendedor Se você recebe Pix com qualquer regularidade — seja por loja, doação de stream ou venda informal — em algum momento vai descobrir o **MED**. Geralmente quando recebe um aviso de que um valor recebido **foi bloqueado**. O MED é o **Mecanismo Especial de Devolução** do Pix, criado pelo Banco Central para agilizar devoluções em casos de fraude, golpe ou falha operacional. Esse post explica como ele funciona, quais são os prazos e o que acontece com o seu saldo se acionarem um contra você. ## O que o MED resolve Antes do MED existir, se uma pessoa caía em golpe Pix e queria seu dinheiro de volta, ela precisava: registrar boletim de ocorrência, ir presencialmente ao banco, esperar dias, e o banco geralmente respondia que **não dá para desfazer Pix**. O BACEN criou o MED em 2021 para mudar isso. Hoje, em casos específicos, o banco do **pagador** pode acionar o sistema, que bloqueia o valor no banco do **recebedor** enquanto a fraude é investigada. ## Quando o MED pode ser acionado O MED **não** serve para arrependimento ("comprei e não gostei"). Ele cobre três cenários: 1. **Fraude** — alguém usou seus dados sem autorização para fazer o Pix 2. **Golpe** — você foi enganado a fazer o Pix (golpe do falso boleto, falso parente, falso CEO, etc.) 3. **Falha operacional** — erro do banco que processou o Pix errado Se nada disso se aplica, o BACEN rejeita o MED. ## O fluxo do ponto de vista de quem recebe Suponha que você é o lado que recebeu o Pix. Alguém acabou de te pagar R$ 200,00 e o valor está no seu saldo. Algumas horas depois: 1. **O pagador entra em contato com o banco dele** alegando fraude ou golpe 2. **O banco do pagador abre um MED no BACEN**, que envia um aviso para instituição do seu Pix 3. **O valor é bloqueado** no seu saldo (no banco do recebedor) — você não pode mais sacar essa parcela 4. **A análise começa** — banco do recebedor tem até 7 dias corridos para avaliar 5. **Decisão final**: - **Aceita pelo BACEN:** o valor é devolvido em até 96 horas. Você perde definitivo. - **Rejeitada:** o valor é liberado de volta para o seu saldo disponível. Você pode ou não ser ouvido nesse processo, dependendo da instituição. Em muitos casos, a decisão sai sem você nem saber que existe um MED — só quando o valor desaparece. ## Os prazos detalhados | Etapa | Prazo | |---|---| | Pagador contesta no banco | até 80 dias após o Pix | | Análise entre instituições | até 11 dias | | Efetivação da devolução (se aceita) | até 96 horas | | Bloqueio extra para rastrear o dinheiro | até 90 dias | Em 2026 entraram em vigor as regras do **MED 2.0**: agora o BACEN pode rastrear o valor por até **cinco transferências em cadeia**. Ou seja, se o fraudador moveu o dinheiro para outras contas para tentar "limpar", o sistema persegue. ## O que o BACEN avalia Não é "quem está certo" — é se há **perfil de comportamento de fraude** na conta que recebeu. Indicadores: - Conta recém-criada - CPF com histórico de outras disputas semelhantes - Movimentação atípica (valores muito acima do padrão dessa conta) - Saques imediatos para terceiros - Conta correndo entre vários CPFs em curto tempo Se você é vendedor honesto com loja há anos, recebendo R$ 50-200 de vários clientes diferentes, o perfil **não bate com fraude**. O MED tende a ser rejeitado. Se a conta tem padrão suspeito, o MED é aceito mesmo se você jurar que era venda legítima. ## O caso da disputa indevida Acontece de cliente entrar em contato com o banco dele alegando "fraude" só porque mudou de ideia, ficou bravo com produto ou se arrependeu da compra. Esse não é o caso de uso do MED, mas o pagador pode acionar **mesmo assim**. Nesses casos, **a análise do BACEN tende a rejeitar** — porque não há perfil de fraude na sua conta. Mas durante os 7-11 dias da análise, **o valor fica retido**. ## Como saber se você foi alvo de um MED Depende da sua plataforma: - **Receber Pix direto pela sua chave pessoal:** o banco te notifica via app que houve um bloqueio. Geralmente sem detalhe. - **Plataformas intermediárias (gateways como BotaPix):** depende da plataforma. Algumas avisam por email + dashboard com prazo e valor; outras só atualizam o saldo sem aviso. No BotaPix, quando detectamos um MED novo via API EFI Bank, **a gente dispara um email para você na hora** com: - Qual transação foi afetada - Valor bloqueado - Prazo BACEN para decisão - Status atual (aberta / aceita / rejeitada) E quando a decisão sai, outro email avisa. ## Pode ter mais de um MED na mesma TX? Sim. Em casos onde a pessoa abre disputa, perde, e abre outra com argumento diferente. O sistema permite. Cada uma é tratada separadamente. ## E se um MED for aceito? Perdi tudo? Em geral, sim — o valor é debitado em definitivo do seu saldo na plataforma intermediária ou no seu banco direto. No BotaPix, a gente: - **Debita o valor** do `balance` (saldo total) - **Reverte a transação** para status `refunded` - **Notifica você** via email + dashboard - **Mantém o evento** no log de auditoria Não tem como "desfazer" uma aceitação do MED do nosso lado — a decisão é do BACEN. Se você acha que foi injusto, o caminho é: 1. **Contatar o suporte** da plataforma para entender o motivo da aceitação 2. **Recorrer junto ao seu banco** (não junto à plataforma) 3. **Em última instância, registrar reclamação no BACEN diretamente** em [bcb.gov.br](https://www.bcb.gov.br) ## Como reduzir o risco de receber um MED indevido Não existe garantia, mas algumas práticas reduzem chance: - **Mantenha registro de cada venda** (comprovante de entrega, conversa de WhatsApp, nota fiscal). Se a plataforma pedir defesa, você apresenta. - **Evite valores altos com clientes desconhecidos** que pagam só por Pix sem outro vínculo - **Use sua conta para fim único** — misturar Pix de venda com Pix pessoal/familiar dificulta defender perfil - **Use uma plataforma que valida CPF do recebedor** — algumas plataformas (BotaPix entre elas) exigem CPF da chave Pix de saque, o que dificulta uso por fraudadores ## O hold period também ajuda Plataformas sérias dão um **tempo de verificação** entre o pedido de saque e o envio do Pix. É uma janela curta que permite detectar um MED novo **antes** que o dinheiro saia da conta — protegendo tanto você quanto a plataforma contra contestações que chegam logo após o pagamento. No BotaPix, o valor entra no seu saldo assim que o pagamento é confirmado e fica disponível para saque na hora. Quando você pede o saque, ele passa por essa verificação de segurança e é processado em poucas horas. Você acompanha tudo pelo dashboard. ## TL;DR - MED é uma proteção legítima do BACEN contra fraude e golpe em Pix - Para quem recebe legítimo, o risco é baixo — o BACEN tende a rejeitar disputas sem perfil de fraude - Durante a análise, o valor fica bloqueado - Plataformas intermediárias podem te ajudar (notificação, contexto, defesa) ou ser opacas - Não tem como bloquear MED 100% — mantenha registros de venda como segurança Se você quer ver o sistema funcionando em prática, [crie sua conta no BotaPix](/register). A gente notifica todos os eventos de MED por email automaticamente, e você acompanha pelo dashboard. Mais detalhes na [documentação](/docs). --- # 5 erros que reduzem doações na sua live (e como corrigir) Fonte: https://botapix.com/blog/5-erros-que-reduzem-doacoes-na-live Você configurou Pix na live, divulgou o link, mas o volume de doações está abaixo do que esperava. Antes de assumir que é "só a audiência pequena", vale revisar **se a configuração está jogando contra você**. Os cinco erros abaixo aparecem em 80% dos canais que vejo. Todos são corrigíveis em minutos. ## Erro 1: QR Code minúsculo no canto da tela O viewer abre o stream no celular, vê seu QR Code com 80x80 pixels enfiado no canto inferior direito, tenta apontar a câmera do outro celular para ele e a leitura falha. Ele desiste. **Por que acontece:** o tutorial que você viu mostrou o QR Code pequeno porque foi gravado em PC, onde "pequeno" ainda é legível. Em mobile, não é. **Como corrigir:** - QR Code com **pelo menos 240px de largura** na tela final (1080p) - Posicionamento **centralizado verticalmente** na lateral (não no canto) - Fundo com contraste suficiente — QR Code preto sobre branco, não sobre overlay translúcido - Teste apontando seu próprio celular para tela em distância normal (50cm) No BotaPix, o widget de QR Code já vem no tamanho certo para 1080p. Se quiser mais destaque, aumente a fonte de navegador no OBS. ## Erro 2: alerta no lugar errado O viewer doou R$ 20 e a mensagem dele apareceu **atrás** do gameplay, parcialmente coberto por algum elemento do jogo. Ele esperava ver seu nome destacado, e nem sabe se você viu. **Por que acontece:** a fonte do widget está com **z-index baixo** ou foi adicionada antes das outras camadas. Em OBS, ordem na lista de fontes = ordem visual (de cima pra baixo). **Como corrigir:** - No OBS, vá na cena ativa e veja a lista de fontes - **Mova o widget de alerta para o topo da lista** (em cima do gameplay, em cima do overlay de webcam) - Confirme que ele não está dentro de um grupo que está atrás de outra coisa - Faça um teste com alerta simulado e veja se aparece **acima de tudo** Bonus: o alerta deve ter contraste forte. Branco sobre verde-escuro é ótimo, transparente sobre gameplay não. ## Erro 3: TTS robotizado em voz padrão Você ativou TTS (text-to-speech) usando a primeira voz que apareceu na lista. É voz de Google Translate dos anos 2010, com pronúncia ruim e cadência mecânica. O viewer doa, a mensagem é lida com tom de robô, e o efeito de "sentir a presença" não acontece. **Por que acontece:** plataformas oferecem várias vozes; a primeira na lista geralmente é a mais antiga/gratuita. **Como corrigir:** - Use uma voz com **timbre humano** — TTS moderno (ElevenLabs e similares) tem PT-BR feminino e masculino convincente - **Teste o volume** — TTS muito alto cobre o áudio do jogo, muito baixo passa despercebido. Faça nível em torno de -18dB no master. - **Não leia tudo** — configure limite máximo de caracteres (60-100). Mensagem gigante vira leitura cansativa. - **Evite vozes "exóticas"** se sua audiência é familiar — voz de robô idiota viraliza em meme, mas reduz a sensação de "doação reconhecida" No BotaPix, oferecemos 4 vozes PT-BR via ElevenLabs (Amanda, Keren, Lax, Brian). Teste todas e veja qual combina com o tom do seu canal. ## Erro 4: link de doação só no chat (sem visual na tela) Você posta o link de doação a cada 20 minutos no chat — mas o viewer que entrou agora não viu, e o que está só ouvindo no segundo monitor também não. O link some no scroll do chat em segundos. **Por que acontece:** chat é canal volátil. Quem está na live por contexto passivo (ouvindo enquanto trabalha) não olha o chat. **Como corrigir:** Pelo menos **um** desses sempre visível em algum canto da tela: - **QR Code permanente** numa região fixa (canto inferior, lateral) - **Texto sobreposto** "Pix → botapix.com/s/seunome" (com fonte legível) - **Painel debaixo da live** (Twitch tem painéis de canal abaixo do player) com o link em texto + botão de copiar Dica de tamanho: o texto do link deve ser **legível em mobile a 720p** — se você consegue ler na sua tela do celular reproduzindo a stream em modo pequeno, tá bom. ## Erro 5: ausência de meta visual Não tem barra de progresso, não tem objetivo. O viewer pensa em doar R$ 10 mas se pergunta "que diferença isso vai fazer?" — e desiste. **Por que acontece:** meta é considerada "complicada de configurar" ou "fica feio na tela", então muitos streamers pulam. **Como corrigir:** - **Defina uma meta clara e específica** — "R$ 500 para o novo microfone", "R$ 1.000 para rifa", "R$ 50 para próximo Just Chatting da semana" - **Mostre a barra de progresso na tela** o tempo todo, mesmo discreta - **Atualize manualmente o texto** com o motivo concreto (não "ajude o canal a crescer") - **Quando bater a meta, celebre na hora** — comemorar visualmente reforça o efeito para os próximos viewers Meta tem 2 efeitos psicológicos comprovados: 1. **Especificidade** — "vamos chegar a R$ 500" é concreto. "Apoie o canal" é abstrato. 2. **Senso de proximidade** — viewer que vê "R$ 480 de R$ 500" se sente o que vai fechar a meta. Conversão sobe nos últimos 5%. No BotaPix, o widget de Meta tem configuração de objetivo, cor da barra, mensagem ao bater. Configura em 2 minutos. ## Bonus: o erro silencioso Tem um sexto que vale citar: **não testar o fluxo todo periodicamente**. A cada 2-3 semanas, faça você mesmo uma doação de R$ 1,00 para o seu próprio canal usando um celular diferente. Veja se: - O QR Code lê na primeira tentativa - O alerta aparece com volume e tempo certos - O TTS lê a mensagem (e não dá erro silencioso) - A página de pagamento carrega rápido - Você confirma o recebimento no painel Algo quebra em silêncio com frequência — atualização do OBS, mudança no widget, bug do navegador interno. Se não testa, vai descobrir quando o viewer reclamar (ou nunca descobrir). ## TL;DR — checklist de 5 minutos - [ ] QR Code 400x400+ centralizado, contraste alto - [ ] Alerta no topo da lista de fontes do OBS - [ ] Voz TTS moderna em PT-BR, volume ~-18dB - [ ] Link visível na tela em algum canto fixo - [ ] Meta com objetivo específico + barra de progresso Se você usa BotaPix, todos esses controles estão no painel **Widgets**. Se ainda não tem conta, [crie aqui](/register). Se quiser entender o setup desde o zero, leia [como receber Pix na live](/blog/como-receber-pix-na-live-guia-streamer).