From dae859f06ea0ca4c90387e4419b1903148712773 Mon Sep 17 00:00:00 2001 From: Lucas Zago Date: Mon, 22 Jun 2026 08:45:29 -0300 Subject: [PATCH] feat: adicionado aba para lojistas --- docs.json | 29 +++++++ pages/authentication.mdx | 29 +++++++ pages/concepts/checkout.mdx | 94 ++++++++++++++++++++++ pages/concepts/overview.mdx | 94 ++++++++++++++++++++++ pages/concepts/pix.mdx | 80 +++++++++++++++++++ pages/concepts/saques.mdx | 80 +++++++++++++++++++ pages/concepts/subscriptions.mdx | 101 +++++++++++++++++++++++ pages/concepts/taxas.mdx | 95 ++++++++++++++++++++++ pages/devmode.mdx | 86 ++++++++++++++++++++ pages/faq/index.mdx | 34 +++++++- pages/guides/primeiro-pagamento.mdx | 120 ++++++++++++++++++++++++++++ pages/production.mdx | 58 ++++++++------ pages/reference/introduction.mdx | 40 ++++++++++ pages/start/welcome.mdx | 69 +++++++++++++++- pages/subscriptions/reference.mdx | 24 ++++++ pages/webhooks.mdx | 92 ++++++++------------- pages/webhooks/security.mdx | 2 + 17 files changed, 1038 insertions(+), 89 deletions(-) create mode 100644 pages/concepts/checkout.mdx create mode 100644 pages/concepts/overview.mdx create mode 100644 pages/concepts/pix.mdx create mode 100644 pages/concepts/saques.mdx create mode 100644 pages/concepts/subscriptions.mdx create mode 100644 pages/concepts/taxas.mdx create mode 100644 pages/guides/primeiro-pagamento.mdx diff --git a/docs.json b/docs.json index 6fc2fa5..be57b61 100644 --- a/docs.json +++ b/docs.json @@ -40,6 +40,35 @@ } ] }, + { + "tab": "Para Lojistas", + "groups": [ + { + "group": "Entenda o Produto", + "pages": [ + "pages/concepts/overview", + "pages/concepts/checkout", + "pages/concepts/pix", + "pages/concepts/subscriptions", + "pages/concepts/saques", + "pages/concepts/taxas" + ] + }, + { + "group": "Guias Rápidos", + "pages": [ + "pages/guides/primeiro-pagamento" + ] + }, + { + "group": "Ajuda", + "pages": [ + "pages/faq/index", + "pages/glossario" + ] + } + ] + }, { "tab": "Guias", "groups": [ diff --git a/pages/authentication.mdx b/pages/authentication.mdx index 5da3f51..3f7c54f 100644 --- a/pages/authentication.mdx +++ b/pages/authentication.mdx @@ -8,6 +8,8 @@ icon: 'key' A **chave de API** é sua credencial de acesso à AbacatePay. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. **Sem uma chave válida, nenhum pedido será aceito.** +Toda requisição para a API da AbacatePay deve incluir sua chave no header `Authorization`. A chave também define o ambiente — uma chave de Dev mode simula transações, uma chave de Produção processa valores reais. Você não muda de URL para mudar de ambiente; muda a chave. + {/*
+ + Causas mais comuns, em ordem de frequência: + + 1. O header `Authorization: Bearer SUA_CHAVE` não está sendo enviado + 2. A chave foi copiada com espaços extras ou caracteres invisíveis + 3. A chave foi revogada no dashboard + 4. Você está usando uma chave de Dev mode em uma URL que exige produção (ou vice-versa) + + Para confirmar que a chave está funcionando, teste diretamente: + ```bash + curl https://api.abacatepay.com/v2/stores/get \ + -H "Authorization: Bearer SUA_CHAVE" + ``` + + + + A chave existe e é válida, mas não tem a permissão para o recurso solicitado. Acesse o dashboard, edite a chave e adicione a permissão necessária. Consulte a tabela de permissões acima para saber qual adicionar. + + + + No dashboard, as chaves de Dev mode têm um indicador visual. Se você não tem certeza, verifique o campo `devMode` em qualquer resposta da API — `true` significa Dev mode, `false` significa Produção. + + + ## Boas práticas de segurança diff --git a/pages/concepts/checkout.mdx b/pages/concepts/checkout.mdx new file mode 100644 index 0000000..e7783ef --- /dev/null +++ b/pages/concepts/checkout.mdx @@ -0,0 +1,94 @@ +--- +title: 'O que é o Checkout?' +description: 'Entenda como funciona a cobrança por link e tela de pagamento da AbacatePay' +icon: 'cart-shopping' +--- + +## A ideia simples + +Um **checkout** é a tela onde seu cliente finaliza o pagamento. É aquela página que aparece quando você clica em "Comprar" em uma loja online — com o resumo do pedido e as opções de pagamento. + +Na AbacatePay, você não precisa construir essa tela. A gente gera ela automaticamente. Você só precisa dizer **o que está sendo vendido** e **qual o valor**. + +--- + +## Como funciona na prática + + + + Pode ser pelo dashboard ou pela API. Você informa o produto e o valor. + + + Um link único e seguro é criado. Ex: `https://app.abacatepay.com/pay/bill_abc123` + + + Por WhatsApp, e-mail, Instagram — qualquer canal. + + + Ele escolhe PIX ou cartão e conclui o pagamento na tela da AbacatePay. + + + Recebe uma notificação imediata de que o pagamento foi confirmado. + + + +--- + +## Dois tipos de checkout + + + + A tela de pagamento fica **no site da AbacatePay**. Você redireciona o cliente para lá e pronto. É o jeito mais rápido — zero configuração de interface. + + **Ideal para:** quem quer começar rápido sem precisar de designer ou desenvolvedor. + + + + A tela de pagamento fica **dentro do seu site**. A AbacatePay processa nos bastidores, mas o cliente nunca sai da sua página. + + **Ideal para:** quem quer uma experiência de compra mais profissional e integrada ao próprio site. Requer desenvolvimento. + + + + + Se você está começando agora, use o **Checkout Hospedado**. É mais rápido e já funciona sem precisar de um desenvolvedor. + + +--- + +## Formas de pagamento aceitas + +| Forma de pagamento | Disponível? | +|--------------------|-------------| +| PIX | ✅ Sim | +| Cartão de crédito | ✅ Sim | +| Boleto | ✅ Sim | +| Parcelamento (até 12x) | ✅ Sim, no cartão | + +--- + +## Perguntas comuns + + + + Por padrão, o link não expira. Você pode configurar uma data de expiração ao criar a cobrança. + + + + Depende. Um link de pagamento comum (`ONE_TIME`) aceita apenas um pagamento. Se você quiser um link reutilizável, use um **Link de Pagamento** com `MULTIPLE_PAYMENTS` — ideal para doações ou pedidos avulsos. + + + + Sim. Você pode configurar o nome, logo e cores da sua loja no dashboard, e eles aparecem automaticamente na tela de checkout. + + + + A cobrança fica com status `PENDING`. Você pode reenviar o link para o cliente a qualquer momento. + + + +--- + + + Siga o guia passo a passo e receba um pagamento real em minutos. + diff --git a/pages/concepts/overview.mdx b/pages/concepts/overview.mdx new file mode 100644 index 0000000..7d1fdd1 --- /dev/null +++ b/pages/concepts/overview.mdx @@ -0,0 +1,94 @@ +--- +title: 'O que é a AbacatePay?' +description: 'Entenda o que a AbacatePay faz pelo seu negócio — sem precisar ser desenvolvedor' +icon: 'store' +--- + + + Esta seção é para quem quer **entender o produto** antes de integrar. Se você já é desenvolvedor e quer ir direto ao código, vá para [Guias → Autenticação](/pages/authentication). + + +## Em uma frase + +A AbacatePay é uma plataforma que permite ao seu negócio **cobrar clientes pela internet** — via PIX, cartão de crédito ou boleto — e **receber esse dinheiro na sua conta**. + +--- + +## O problema que a AbacatePay resolve + +Imagine que você tem uma loja online, um serviço de assinatura ou vende infoprodutos. Para cobrar seus clientes, você precisaria: + +- Contratar um banco ou adquirente (processo longo e burocrático) +- Lidar com dezenas de regras técnicas de cada meio de pagamento +- Construir toda a tela de pagamento do zero +- Gerenciar estornos, inadimplência, notificações... + +A AbacatePay cuida de tudo isso por você. Você foca no seu produto; a gente cuida do dinheiro. + +--- + +## O que você pode fazer com a AbacatePay + + + + Crie um link de pagamento em segundos e compartilhe com seu cliente — pelo WhatsApp, e-mail ou Instagram. Funciona como um carrinho de compras, sem precisar de site. + + + + Gere um QR Code PIX na hora. O cliente escaneia e o dinheiro cai em segundos, qualquer dia, qualquer hora. + + + + Aceite cartão de crédito com parcelamento em até 12x. Tudo em uma tela de pagamento pronta, sem precisar construir nada. + + + + Configure uma cobrança recorrente e a AbacatePay cobra seu cliente automaticamente todo mês — ideal para cursos, mentorias ou serviços com mensalidade. + + + + Quando quiser, transfira o saldo acumulado para sua conta bancária de forma simples e rápida. + + + + Crie promoções com desconto percentual ou fixo e distribua para seus clientes. + + + +--- + +## Como funciona o fluxo de um pagamento + +``` +Seu cliente → Tela de pagamento → AbacatePay → Você recebe a confirmação → Saldo disponível +``` + +1. Você cria uma cobrança (via dashboard ou API) +2. A AbacatePay gera uma tela de pagamento segura +3. Seu cliente paga (PIX, cartão ou boleto) +4. Você recebe uma notificação automática +5. O valor entra no seu saldo na AbacatePay +6. Você saca para sua conta quando quiser + +--- + +## Quem usa a AbacatePay? + +- **Infoprodutores** que vendem cursos e mentorias +- **SaaS e startups** que cobram assinatura mensal +- **E-commerces** que precisam de checkout rápido +- **Freelancers** que querem um jeito simples de cobrar clientes +- **Lojas físicas** que querem aceitar pagamento online + +--- + +## Próximos passos + + + + Um guia passo a passo para você receber um pagamento real sem escrever código. + + + Saiba mais sobre Checkout, PIX, Assinaturas e Saques em linguagem simples. + + diff --git a/pages/concepts/pix.mdx b/pages/concepts/pix.mdx new file mode 100644 index 0000000..0627290 --- /dev/null +++ b/pages/concepts/pix.mdx @@ -0,0 +1,80 @@ +--- +title: 'O que é o PIX?' +description: 'Como usar o PIX para receber pagamentos instantâneos pelo seu negócio' +icon: 'qrcode' +--- + +## PIX: o que todo mundo já sabe + +O PIX é o sistema de pagamento instantâneo do Banco Central do Brasil. Funciona 24 horas por dia, 7 dias por semana, e o dinheiro cai na conta em segundos. + +Você já usa PIX no dia a dia. Na AbacatePay, a gente traz isso para o seu negócio de forma profissional. + +--- + +## Como a AbacatePay usa o PIX + +A AbacatePay gera para você um **QR Code** ou um **código copia-e-cola** único para cada cobrança. Seu cliente escaneia ou cola no banco dele e o pagamento é confirmado em segundos. + + + + Uma imagem que o cliente escaneia com o aplicativo do banco. Ideal para cobranças em sites, landing pages ou imagens no WhatsApp. + + + Um código de texto que o cliente cola no app do banco. Funciona em qualquer canal de texto — SMS, e-mail, chat. + + + +--- + +## Quando usar PIX vs outras formas de pagamento? + +| | PIX | Cartão | Boleto | +|---|---|---|---| +| **Confirmação** | Segundos | Minutos a horas | 1-3 dias úteis | +| **Disponível** | 24/7 | 24/7 | Dias úteis | +| **Parcelamento** | Não | Sim (até 12x) | Não | +| **Taxa** | Menor | Maior | Média | +| **Cancelamento fácil** | Sim | Sim | Sim | + +**Regra prática:** +- Produto de baixo valor ou urgente → PIX +- Produto de alto valor → cartão com parcelamento +- Cliente sem cartão → boleto + +--- + +## O que acontece depois que o cliente paga? + +1. O pagamento é confirmado em segundos +2. O valor entra no seu **saldo na AbacatePay** +3. Você recebe uma **notificação automática** (se tiver webhook configurado) +4. Quando quiser, você **saca** o valor para sua conta bancária + +--- + +## Perguntas comuns + + + + Sim. Por padrão, o QR Code PIX expira em 30 minutos após a criação. Você pode configurar um prazo diferente ao criar a cobrança. + + + + Sim, não há valor mínimo ou máximo definido pela AbacatePay. Limitações de valor do Banco Central podem se aplicar dependendo do banco do seu cliente. + + + + Você pode verificar o status da cobrança no dashboard. Se configurou webhooks, receberá uma notificação automática assim que o pagamento for confirmado. + + + + Se o cliente transferir um valor diferente do QR Code, o pagamento pode não ser confirmado automaticamente. Para evitar isso, sempre use o QR Code gerado pela AbacatePay — ele já tem o valor embutido. + + + +--- + + + Siga o guia e gere seu primeiro QR Code em minutos. + diff --git a/pages/concepts/saques.mdx b/pages/concepts/saques.mdx new file mode 100644 index 0000000..7053f18 --- /dev/null +++ b/pages/concepts/saques.mdx @@ -0,0 +1,80 @@ +--- +title: 'Como receber seu dinheiro' +description: 'Entenda como funciona o saldo e como transferir o dinheiro para sua conta bancária' +icon: 'money-bill-transfer' +--- + +## O fluxo do dinheiro + +Quando um cliente paga pelo AbacatePay, o dinheiro não vai diretamente para o seu banco. Ele vai primeiro para o seu **saldo na AbacatePay**. Depois, você faz um **saque** para transferir esse saldo para a sua conta. + +``` +Cliente paga → Saldo na AbacatePay → Você saca → Sua conta bancária +``` + +--- + +## Por que funciona assim? + +Esse modelo é padrão no mercado de pagamentos. Ele permite que a AbacatePay: + +- Processe estornos sem problemas +- Garanta a segurança das transações +- Consolide múltiplos pagamentos antes de transferir + +--- + +## Quando o dinheiro fica disponível? + +| Forma de pagamento | Disponibilidade no saldo | +|-------------------|--------------------------| +| PIX | Imediato após confirmação | +| Cartão de crédito | Após o prazo de liquidação (consulte o dashboard) | +| Boleto | Após a compensação bancária (1-3 dias úteis) | + +--- + +## Como fazer um saque + + + + Entre em [app.abacatepay.com](https://app.abacatepay.com) com sua conta. + + + No menu lateral, clique em **Saques** ou **Financeiro**. + + + Digite o valor e os dados da conta de destino (banco, agência, conta e CPF/CNPJ do titular). + + + Revise os dados e confirme. O valor é transferido normalmente no mesmo dia útil. + + + +--- + +## Perguntas comuns + + + + Sim. O valor mínimo de saque é definido pela AbacatePay. Consulte o dashboard para ver o limite atual. + + + + Sim, desde que você forneça os dados bancários corretos do destinatário, incluindo o CPF ou CNPJ do titular da conta. + + + + Saques solicitados em dias úteis são processados no mesmo dia. Saques em fins de semana ou feriados são processados no próximo dia útil. + + + + A AbacatePay cobra uma taxa sobre cada transação processada. Essa taxa é descontada automaticamente do valor recebido antes de entrar no seu saldo. Consulte a [página de precificação](https://abacatepay.com) para os valores atuais. + + + +--- + + + Veja o FAQ com as perguntas mais comuns sobre saques e financeiro. + diff --git a/pages/concepts/subscriptions.mdx b/pages/concepts/subscriptions.mdx new file mode 100644 index 0000000..88c0ca7 --- /dev/null +++ b/pages/concepts/subscriptions.mdx @@ -0,0 +1,101 @@ +--- +title: 'O que são Assinaturas?' +description: 'Entenda como cobrar seus clientes todo mês de forma automática' +icon: 'rotate' +--- + +## A ideia + +Uma assinatura é uma **cobrança automática e recorrente**. Em vez de você precisar cobrar seu cliente toda vez, a AbacatePay faz isso automaticamente no intervalo que você definiu — mensal, semanal ou anual. + +Pense em como funciona o Netflix, Spotify ou qualquer academia: o cliente assina uma vez e é cobrado automaticamente todo mês. Você pode fazer exatamente isso para o seu negócio. + +--- + +## Para que serve? + + + + Cobranças mensais para alunos de um curso ou programa de mentoria continuada. + + + Plano mensal ou anual para o seu serviço ou ferramenta online. + + + Acesso a grupo exclusivo, comunidade ou clube de assinantes. + + + Produto ou serviço entregue periodicamente com cobrança automática. + + + +--- + +## Como funciona o ciclo + + + + No dashboard, você define o produto, o preço e o ciclo (mensal, anual, semanal). + + + Ele paga a primeira cobrança. A assinatura está ativa. + + + No próximo ciclo (ex: daqui a 30 dias), a AbacatePay tenta cobrar o cliente automaticamente. + + + A cada pagamento confirmado ou falha, você recebe uma notificação. + + + Você ou o cliente podem cancelar a assinatura a qualquer momento pelo dashboard ou pela API. + + + +--- + +## O que acontece se o pagamento falhar? + +A AbacatePay tenta cobrar de novo automaticamente. Você pode configurar: + +- **Quantas tentativas** fazer (até 10) +- **Quantos dias esperar** entre cada tentativa (1 a 30 dias) + +Se todas as tentativas falharem, a assinatura é marcada como `FAILED` e você é notificado. + +--- + +## Ciclos disponíveis + +| Ciclo | Frequência | +|-------|-----------| +| `WEEKLY` | Toda semana | +| `MONTHLY` | Todo mês | +| `YEARLY` | Todo ano | + +--- + +## Perguntas comuns + + + + Essa funcionalidade está em nosso roadmap. Por enquanto, você pode oferecer um produto de teste separado com valor zerado, ou gerenciar o período de trial manualmente. + + + + Sim. Você pode alterar o plano de uma assinatura ativa a qualquer momento — o novo valor passa a valer no próximo ciclo. + + + + Sim. Você pode criar cupons e aplicá-los ao criar ou atualizar uma assinatura. + + + + Você pode cancelar pelo dashboard ou pela API. Se quiser que o próprio cliente cancele de forma self-service, você precisa criar essa funcionalidade no seu site usando a API da AbacatePay. + + + +--- + + + Veja o guia completo para começar a receber mensalidades. + diff --git a/pages/concepts/taxas.mdx b/pages/concepts/taxas.mdx new file mode 100644 index 0000000..9977637 --- /dev/null +++ b/pages/concepts/taxas.mdx @@ -0,0 +1,95 @@ +--- +title: 'Taxas e tarifas' +description: 'Entenda quanto custa usar a AbacatePay — sem mensalidade, sem surpresas' +icon: 'receipt' +--- + + + A AbacatePay **não cobra mensalidade**. Você paga apenas quando recebe ou movimenta dinheiro — e as taxas já são descontadas automaticamente do valor antes de entrar no seu saldo. + + +--- + +## Receber pagamentos + +| Forma de pagamento | Taxa | +|--------------------|------| +| PIX | R$ 0,80 por transação | +| Cartão de crédito à vista | 3,50% + R$ 0,60 | +| Cartão parcelado (2x a 6x) | 4,00% + R$ 0,60 | +| Cartão parcelado (7x a 12x) | 4,50% + R$ 0,60 | +| Boleto bancário | R$ 2,50 por boleto gerado | + + + As taxas de cartão incidem sobre o **valor total da transação**. O valor fixo de R$ 0,60 é cobrado independentemente do valor. + + +--- + +## Sacar dinheiro + +| Tipo de transferência | Custo | +|-----------------------|-------| +| PIX (primeiros 30 saques do mês) | R$ 0,80 por saque | +| PIX (a partir do 31º saque no mês) | R$ 2,50 por saque | +| TED | R$ 5,00 por transferência | + + + O limite diário varia conforme a conta. Novas lojas começam com um limite menor que aumenta automaticamente após a verificação de conta. Consulte o dashboard para ver o limite atual da sua loja. + + +--- + +## Antecipação de recebíveis + +Recebíveis de cartão de crédito têm prazo de liquidação. Se você quiser antecipar e receber antes do prazo, é possível mediante taxa: + +| | Taxa | +|--|------| +| Antecipação de recebíveis de cartão | 1,50% ao mês | + +--- + +## Como as taxas são cobradas + +Você **nunca paga separadamente**. O fluxo é sempre: + +``` +Cliente paga R$ 100,00 via PIX +→ AbacatePay desconta R$ 0,80 +→ R$ 99,20 entra no seu saldo +``` + +O campo `platformFee` nas respostas da API mostra exatamente quanto foi descontado em cada transação, em centavos. + +--- + +## Perguntas frequentes + + + + Não. A taxa do boleto (R$ 2,50) é cobrada apenas quando o boleto é **pago**. Se o cliente não pagar, nenhuma taxa é descontada. + + + + Você recebe cada parcela individualmente conforme a operadora de cartão a liquida. Se o cliente parcelou em 10x, você recebe 10 créditos separados ao longo dos meses — não o valor total de uma vez. + + + + Sim. O contador reinicia no início de cada mês calendário. + + + + Não. Criar conta, acessar o dashboard, criar produtos, cupons e links de pagamento são gratuitos. Você só paga quando há movimentação financeira. + + + + Sim. As taxas acima são as padrão. Dependendo do volume de transações da sua loja, as taxas podem ser negociadas. Entre em contato com o suporte para saber mais. + + + +--- + + + Consulte as taxas da sua conta diretamente no dashboard em **Perfil → Taxas**, ou entre em contato: ajuda@abacatepay.com + diff --git a/pages/devmode.mdx b/pages/devmode.mdx index b655ab8..cf74fb1 100644 --- a/pages/devmode.mdx +++ b/pages/devmode.mdx @@ -91,6 +91,92 @@ Os números abaixo são sempre **rejeitados** no Dev mode, para você testar o f - `4000000000000069` - `4000000000000101` +## Checklist antes de ir para produção + +Use esta lista para saber que sua integração está pronta. O progresso é salvo no seu navegador. + +
+ {[ + { id: "auth", label: "Autenticação funcionando com chave de Dev mode" }, + { id: "create", label: <>Criação de cobrança retornando success: true }, + { id: "card", label: <>Fluxo de pagamento testado com cartão 4242 4242 4242 4242 }, + { id: "pix", label: <>Fluxo de pagamento PIX testado com /transparents/simulate-payment }, + { id: "webhook", label: <>Webhook recebendo e processando checkout.completed (ou evento relevante) }, + { id: "idempotent", label: "Idempotência implementada (verificação de IDs duplicados)" }, + { id: "errors", label: <>Tratamento de erros 4xx e 5xx implementado }, + { id: "envvar", label: "Chave de API armazenada em variável de ambiente (nunca no código)" }, + { id: "failures", label: "Cenários de falha testados (cartões rejeitados, dados inválidos)" }, + ].map(({ id, label }, i) => ( + + ))} +
+ +
+
+ Progresso + 0 / 9 concluídos +
+
+
+
+
+ +