> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Aceite pagamentos no seu projeto no Macaly

A integração do Macaly com o Stripe permite aceitar pagamentos únicos e recorrentes (assinaturas) diretamente no seu projeto. Um ambiente de testes totalmente funcional é criado automaticamente, então você pode começar a construir e testar sem ter uma conta no Stripe. Quando estiver pronto para entrar no ar, conecte sua conta do Stripe e mude para o modo de produção.

<Callout icon="user">
  Disponível nos [**planos Pro e Agência**](/docs/pt-BR/welcome/pricing)
</Callout>

## Como adicionar pagamentos ao seu projeto

Descreva ao agente, no chat, o que você precisa em termos de pagamento. Por exemplo:

```
Quero vender meus produtos de skincare online. Preciso de uma loja
com catálogo e checkout para os clientes pagarem com cartão.
```

```
Escrevi um e-book e quero vendê-lo por $19. Crie uma página
onde as pessoas possam pagar e baixar o e-book na hora.
```

```
Estou lançando uma aula de ioga online mensal por $29/mês. Crie uma
landing page onde os alunos possam se cadastrar e iniciar a assinatura.
```

O agente cria seu projeto com um fluxo de pagamento completo e prepara um ambiente de testes do Stripe em segundo plano.

Para adicionar pagamentos, você também pode começar pela aba **Pagamentos**, na barra de navegação superior.

Você pode começar a testar imediatamente com o cartão de teste exibido na aba Pagamentos:

| Campo | Valor |
| - | - |
| Número do cartão | 4242 4242 4242 4242 |
| Validade | Qualquer data futura (ex.: 01/30) |
| CVC | Quaisquer 3 dígitos (ex.: 111) |
| CEP | Qualquer valor (ex.: 11000) |

Acesse seu projeto, faça uma compra de teste e verifique a experiência de checkout.

<Tip>
  Você também pode testar cenários de erro, como cartões recusados ou dados de pagamento inválidos, usando os cartões de teste específicos do Stripe. Veja a [documentação de testes do Stripe](https://docs.stripe.com/testing#declined-payments) para a lista completa de números de cartão de teste e dos erros que eles simulam.
</Tip>

## Como ativar sua área de testes segura

Quando o Macaly cria seu ambiente de testes, ele prepara um sandbox do Stripe. Esse sandbox funciona de imediato e permite testar pagamentos, mas não está vinculado a nenhuma conta do Stripe. Sandboxes não reivindicados expiram após 60 dias.

Ao reivindicar o sandbox, você o conecta à sua conta do Stripe. Depois disso, o sandbox é seu e você pode gerenciá-lo diretamente no Stripe Dashboard.

Você pode reivindicar o sandbox de duas formas: pela aba **Pagamentos** do seu projeto ou pelo e-mail que o Stripe envia depois que o ambiente de testes é criado.

Reivindicar o sandbox também é o primeiro passo para aceitar pagamentos reais. Para entrar no ar, você precisará reivindicar o sandbox, verificar sua empresa no Stripe e inserir suas chaves de API de produção.

<iframe src="https://www.youtube.com/embed/SVcTB6UZlIc" />

<Steps>
  <Step title="Abra a aba Pagamentos">
    Abra a aba **Pagamentos** no seu projeto. Em "Ative sua área de testes segura", você verá o botão **Reivindicar seu sandbox do Stripe**.
  </Step>

  <Step title="Clique em Reivindicar seu sandbox do Stripe">
    O Stripe abre em uma nova aba, na página **Claim your sandbox**.

    Se você já tem uma conta no Stripe, selecione-a na lista. Caso contrário, clique em **+ Create new account** para criar uma sem custo.

    Clique em **Continue** para prosseguir.
  </Step>

  <Step title="Informe os dados da sua empresa">
    O Stripe pedirá algumas informações básicas:

    1. **Business name and location.** Informe o nome da empresa e selecione seu país. Clique em **Continue**.
    2. **Business website and description.** Informe a URL do seu site e uma breve descrição dos seus produtos ou serviços. Você pode pular esta etapa clicando em **Skip**.
    3. **Intended use of Stripe.** Selecione os tipos de pagamento relevantes para o seu negócio (por exemplo, pagamentos únicos ou recorrentes). Esta etapa também pode ser pulada.
  </Step>

  <Step title="Conclua a configuração do sandbox">
    Na tela final, o Stripe apresenta um resumo dos próximos passos: concluir a configuração, mudar para o modo de produção e começar a aceitar pagamentos. Clique em **Go to sandbox** para finalizar.
  </Step>

  <Step title="Volte ao Macaly">
    Volte ao Macaly. A aba Pagamentos deve exibir **Os pagamentos estão em modo de teste** em laranja, confirmando que a reivindicação foi concluída.

    <Info>
      A atualização do status pode levar alguns instantes para sincronizar. Se o botão de reivindicação ainda estiver visível, atualize a página.
    </Info>
  </Step>
</Steps>

## Como mudar para o modo de produção

Quando estiver pronto para aceitar pagamentos reais, você precisa ativar sua conta do Stripe e conectar suas chaves de API de produção ao Macaly.

<Warning>
  Você é responsável por todas as obrigações legais e fiscais relacionadas aos pagamentos que aceitar por meio do seu projeto. Consulte um contador ou consultor tributário se tiver dúvidas sobre suas obrigações.
</Warning>

### Ative sua conta do Stripe

Antes de acessar as chaves de API de produção, o Stripe exige que você verifique sua empresa. É um processo de cadastro padrão, que acontece inteiramente do lado do Stripe.

<Steps>
  <Step title="Abra o Stripe Dashboard">
    Acesse [dashboard.stripe.com](https://dashboard.stripe.com) e entre na conta que você usou para reivindicar o sandbox.
  </Step>

  <Step title="Conclua o guia de configuração">
    O Stripe pedirá que você conclua a configuração da conta. Normalmente isso inclui:

    * Dados da empresa (razão social, endereço, tipo de negócio)
    * Verificação de identidade pessoal
    * Conta bancária ou dados de repasse para o recebimento dos valores

    Siga o guia de configuração do Stripe até que todas as etapas estejam marcadas como concluídas.
  </Step>

  <Step title="Aguarde a verificação">
    O Stripe analisa suas informações e ativa sua conta. Geralmente isso é instantâneo, mas pode levar alguns dias, dependendo do seu país e do tipo de negócio.

    Depois de verificada, sua conta está no ar e suas chaves de API de produção ficam disponíveis no Dashboard.
  </Step>
</Steps>

<Info>
  Você pode continuar construindo e testando seu projeto no modo de teste enquanto espera o Stripe verificar sua conta.
</Info>

### Insira suas chaves de API de produção

Depois que sua conta do Stripe for verificada, copie suas chaves de produção para o Macaly.

<Steps>
  <Step title="Copie suas chaves do Stripe Dashboard">
    No Stripe Dashboard, suas chaves de API aparecem no card **API keys**, no lado direito da página inicial. Você também as encontra em **Developers → API keys**, na parte de baixo da barra lateral.

    Você verá duas chaves:

    * A **Chave publicável** começa com `pk_live_`.
    * A **Chave secreta** começa com `sk_live_`.

    Copie as duas chaves.

    <Warning>
      Sua chave secreta dá acesso total à sua conta do Stripe. Nunca a compartilhe nem a cole no chat.
    </Warning>
  </Step>

  <Step title="Adicione suas chaves no Macaly">
    Na aba **Pagamentos**, clique em **Adicionar conexão ao Stripe**. Cole cada chave no campo correspondente e clique em **Salvar chaves de API**. Confira se você está usando as chaves de produção (que começam com `pk_live_` e `sk_live_`) e não as chaves de teste (`pk_test_` e `sk_test_`).
  </Step>

  <Step title="Mude para o modo de produção">
    Clique em **Mudar para o modo de produção**. O Macaly reconfigura seu projeto para usar sua conta do Stripe em produção. O status passa para **Os pagamentos estão em modo de produção**, em verde.
  </Step>

  <Step title="Publique seu projeto">
    Publique seu projeto para colocar as alterações no ar. Os pagamentos reais só são processados no site publicado, não na prévia.
  </Step>
</Steps>

## Como gerenciar sua integração

Todas as configurações de pagamento ficam na aba **Pagamentos**:

* **Abrir o Stripe** abre o Stripe Dashboard, onde você pode revisar transações, fazer reembolsos e acompanhar repasses.
* **Mudar para o modo de produção / Mudar para o modo de teste** permite alternar entre os ambientes a qualquer momento, sem afetar o código do seu projeto.
* **Gerenciar conexão ao Stripe** permite atualizar suas chaves de API de produção depois da configuração inicial.
* **Testar pagamentos** exibe os dados do cartão de teste para consulta enquanto você está no modo de teste.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O que é um sandbox e como ele é diferente da minha conta do Stripe?">
    Um sandbox é um ambiente de testes temporário que o Macaly cria para você. Ele vem com as próprias chaves de API de teste e permite simular pagamentos sem mexer em dinheiro real. Ele **não** é a sua conta do Stripe. Quando você reivindica o sandbox, vincula-o à sua conta real do Stripe. Até lá, o sandbox é anônimo e expira após 60 dias.
  </Accordion>

  <Accordion title="Os pagamentos de teste não estão sendo concluídos">
    Confira se você está usando o número de cartão de teste **4242 4242 4242 4242**, com qualquer data de validade futura, qualquer CVC de 3 dígitos e qualquer CEP. Se o problema continuar, revise o chat em busca de detalhes do erro ou peça ao agente que diagnostique o fluxo de pagamento.
  </Accordion>

  <Accordion title="Qual é a diferença entre o modo de teste e o modo de produção?">
    O **modo de teste** usa o ambiente de sandbox com chaves de teste. Todos os pagamentos são simulados e nenhum dinheiro real é movimentado. O **modo de produção** usa sua conta do Stripe verificada com as chaves de produção. O dinheiro real é cobrado e depositado na sua conta bancária. Você pode alternar entre os modos a qualquer momento na aba Pagamentos. Trocar de modo não afeta o código do seu projeto, apenas quais chaves do Stripe estão ativas.
  </Accordion>

  <Accordion title="Não encontro as chaves de API de produção no meu Stripe Dashboard">
    Reivindicar o sandbox e verificar sua conta do Stripe são duas etapas separadas. Reivindicar vincula o sandbox à sua conta, mas você ainda precisa concluir a verificação da empresa no Stripe (identidade, dados da empresa, conta bancária) antes que as chaves de produção sejam geradas. Abra o Stripe Dashboard e siga o guia de configuração para terminar a verificação. Se você só vê chaves de teste (que começam com `pk_test_` e `sk_test_`), sua conta ainda não foi totalmente verificada.
  </Accordion>

  <Accordion title="O Macaly ainda mostra o modo de teste depois que verifiquei minha conta do Stripe">
    Verificar sua conta do Stripe não muda o Macaly automaticamente para o modo de produção. Você precisa inserir manualmente suas chaves de API de produção na aba Pagamentos e depois clicar em **Mudar para o modo de produção**. O Macaly mantém você no modo de teste até que você faça essa mudança explicitamente.
  </Accordion>

  <Accordion title="Os pagamentos reais não estão sendo concluídos">
    Verifique três coisas, nesta ordem:

    1. **Você publicou o projeto?** Os pagamentos reais só são processados no site publicado, não na prévia.
    2. **Suas chaves estão corretas?** Confirme que você inseriu a **Chave publicável** (que começa com `pk_live_`) e a **Chave secreta** (que começa com `sk_live_`). Se você colou chaves de teste sem querer, clique em **Gerenciar conexão ao Stripe** e atualize-as.
    3. **Sua conta do Stripe está totalmente verificada?** Abra o Stripe Dashboard e veja se há etapas pendentes no guia de configuração. O Stripe pode exigir documentos adicionais antes de processar pagamentos reais.
  </Accordion>

  <Accordion title="O que acontece quando meu sandbox expira?">
    Sandboxes não reivindicados expiram após 60 dias. Abra a aba Pagamentos e clique em **Configurar novo sandbox** para criar um novo ambiente. O código de pagamento que você já tem não muda. Se você já tinha reivindicado o sandbox e verificado sua conta do Stripe, precisará inserir suas chaves de produção de novo depois de criar um novo sandbox.
  </Accordion>
</AccordionGroup>

## Bom saber

* **As taxas do Stripe se aplicam.** O Macaly não cobra taxas adicionais sobre os pagamentos. Valem as taxas de processamento padrão do Stripe em cada transação (veja [stripe.com/pricing](https://stripe.com/pricing)).
* **Expiração do sandbox.** Ambientes de teste não reivindicados expiram após 60 dias. Se isso acontecer, abra a aba Pagamentos e clique em **Configurar novo sandbox** para criar um novo.
* **Os webhooks são gerenciados automaticamente.** O Macaly configura e mantém todos os endpoints de webhook. Não é preciso nenhuma configuração manual no Stripe Dashboard.
* **Os ambientes de teste e de produção são isolados.** As transações de teste não aparecem na sua conta do Stripe em produção e nenhuma cobrança real é feita.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.