> ## 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

> Aceita pagamentos no teu projeto Macaly

A integração Stripe do Macaly permite-te aceitar pagamentos únicos e recorrentes (subscrições) diretamente dentro do teu projeto. Um ambiente de teste totalmente funcional é criado automaticamente, para que possas começar a criar e a testar sem uma conta Stripe. Quando estiveres pronto para avançar, liga a tua conta Stripe e muda para o modo ativo.

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

## Adicionar pagamentos ao teu projeto

Descreve as tuas necessidades de pagamento ao agente no chat. Por exemplo:

```
Quero vender os meus produtos de cuidados de pele online. Preciso de
uma loja com catálogo e checkout para que os clientes possam pagar com cartão.
```

```
Escrevi um e-book e quero vendê-lo por 19 €. Cria uma página onde as
pessoas possam pagar e transferi-lo de imediato.
```

```
Estou a lançar uma aula de ioga mensal online por 29 €/mês. Constrói uma
landing page onde os membros possam registar-se e iniciar a subscrição.
```

O agente cria o teu projeto com um fluxo de pagamento completo e prepara um ambiente de teste Stripe em segundo plano.

Para adicionar pagamentos, também podes começar pelo separador **Pagamentos** na barra de navegação superior.

Podes começar a testar de imediato usando o cartão de teste apresentado no separador 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) |
| Código postal | Qualquer valor (ex.: 11000) |

Navega até ao teu projeto, completa uma compra de teste e verifica a experiência de checkout.

<Tip>
  Também podes testar cenários de erro, como cartões recusados ou dados de pagamento inválidos, usando os cartões de teste dedicados da Stripe. Consulta a [documentação de testes da Stripe](https://docs.stripe.com/testing#declined-payments) para a lista completa de números de cartão de teste e dos erros que simulam.
</Tip>

## Ativar a tua área de testes segura

Quando o Macaly cria o teu ambiente de teste, prepara um sandbox Stripe. Este sandbox funciona de imediato e permite-te testar pagamentos, mas não está ligado a nenhuma conta Stripe. Os sandboxes não reivindicados expiram ao fim de 60 dias.

Reivindicar o sandbox liga-o à tua conta Stripe. Depois de reivindicado, o sandbox é teu e podes geri-lo diretamente na Stripe Dashboard.

Podes reivindicar o sandbox de duas formas: a partir do separador **Pagamentos** no teu projeto, ou através do email que a Stripe te envia depois de o ambiente de teste ser criado.

Reivindicar é também o primeiro passo para aceitar pagamentos reais. Para avançares, vais precisar de reivindicar o sandbox, fazer verificar o teu negócio pela Stripe e introduzir as tuas chaves de API ativas (Live).

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

<Steps>
  <Step title="Abre o separador Pagamentos">
    Abre o separador **Pagamentos** no teu projeto. Em "Ativa a tua área de testes segura" vais ver um botão **Reivindicar o teu sandbox do Stripe**.
  </Step>

  <Step title="Clica em Reivindicar o teu sandbox do Stripe">
    A Stripe abre num novo separador com a página **Claim your sandbox**.

    Se já tiveres uma conta Stripe, seleciona-a na lista. Caso contrário, clica em **+ Create new account** para criar uma sem custo.

    Clica em **Continue** para avançar.
  </Step>

  <Step title="Indica os dados do teu negócio">
    A Stripe vai pedir-te algumas informações básicas:

    1. **Nome e localização do negócio.** Introduz o nome do teu negócio e seleciona o teu país. Clica em **Continue**.
    2. **Site e descrição do negócio.** Indica o URL do teu site e uma breve descrição dos teus produtos ou serviços. Este passo pode ser saltado clicando em **Skip**.
    3. **Uso pretendido da Stripe.** Seleciona os tipos de pagamento relevantes para o teu negócio (por exemplo, pagamentos únicos ou recorrentes). Este passo também pode ser saltado.
  </Step>

  <Step title="Completa a configuração do sandbox">
    No ecrã final, a Stripe apresenta um resumo dos próximos passos: completar a tua configuração, mudar para o modo ativo e começar a aceitar pagamentos. Clica em **Go to sandbox** para terminar.
  </Step>

  <Step title="Volta ao Macaly">
    Regressa ao Macaly. O separador Pagamentos deverá agora mostrar **Os pagamentos estão em modo de teste** a laranja, confirmando que a reivindicação foi bem-sucedida.

    <Info>
      As atualizações de estado podem demorar alguns instantes a sincronizar. Se o botão de reivindicação ainda estiver visível, atualiza a página.
    </Info>
  </Step>
</Steps>

## Mudar para o modo ativo

Quando estiveres pronto para aceitar pagamentos reais, precisas de ativar a tua conta Stripe e ligar as tuas chaves de API ativas ao Macaly.

<Warning>
  És responsável por todas as obrigações legais e fiscais relacionadas com os pagamentos que aceitas através do teu projeto. Consulta um consultor fiscal se tiveres dúvidas sobre as tuas obrigações.
</Warning>

### Ativa a tua conta Stripe

Antes de poderes aceder às chaves de API ativas, a Stripe exige que verifiques o teu negócio. É um processo de integração padrão que acontece inteiramente do lado da Stripe.

<Steps>
  <Step title="Abre a Stripe Dashboard">
    Vai a [dashboard.stripe.com](https://dashboard.stripe.com) e inicia sessão com a conta que usaste para reivindicar o sandbox.
  </Step>

  <Step title="Completa o guia de configuração">
    A Stripe vai convidar-te a completar a configuração da tua conta. Normalmente inclui:

    * Dados do negócio (denominação legal, morada, tipo de negócio)
    * Verificação de identidade pessoal
    * Conta bancária ou dados de pagamento para receberes os fundos

    Segue o guia de configuração da Stripe até todos os passos estarem marcados como concluídos.
  </Step>

  <Step title="Aguarda a verificação">
    A Stripe revê as tuas informações e ativa a tua conta. Normalmente é imediato, mas pode demorar até alguns dias, dependendo do teu país e do tipo de negócio.

    Depois de verificada, a tua conta fica ativa e as tuas chaves de API ativas ficam disponíveis na Dashboard.
  </Step>
</Steps>

<Info>
  Podes continuar a criar e a testar o teu projeto em modo de teste enquanto esperas que a Stripe verifique a tua conta.
</Info>

### Introduz as tuas chaves de API ativas

Depois de a tua conta Stripe estar verificada, copia as tuas chaves ativas para o Macaly.

<Steps>
  <Step title="Copia as tuas chaves da Stripe Dashboard">
    Na Stripe Dashboard, as tuas chaves de API são apresentadas no cartão **API keys** do lado direito da página inicial. Também as encontras em **Developers → API keys**, no fundo da barra lateral.

    Vais ver duas chaves:

    * A **Publishable key** começa por `pk_live_`.
    * A **Secret key** começa por `sk_live_`.

    Copia ambas as chaves.

    <Warning>
      A tua chave secreta dá acesso total à tua conta Stripe. Nunca a partilhes nem a coles no chat.
    </Warning>
  </Step>

  <Step title="Adiciona as tuas chaves no Macaly">
    No separador **Pagamentos**, clica em **Adicionar ligação ao Stripe**. Cola cada chave no campo correspondente e clica em **Guardar chaves de API**. Certifica-te de que estás a usar as tuas chaves ativas (que começam por `pk_live_` e `sk_live_`), e não as chaves de teste (`pk_test_` e `sk_test_`).
  </Step>

  <Step title="Muda para o modo ativo">
    Clica em **Mudar para o modo ativo**. O Macaly reconfigura o teu projeto para usar a tua conta Stripe ativa. O estado atualiza-se para **Os pagamentos estão ativos** a verde.
  </Step>

  <Step title="Publica o teu projeto">
    Publica o teu projeto para aplicar as alterações. Os pagamentos ativos só são processados no site publicado, não na pré-visualização.
  </Step>
</Steps>

## Gerir a tua integração

Todas as definições de pagamento estão acessíveis a partir do separador **Pagamentos**:

* **Abrir o Stripe** abre a Stripe Dashboard, onde podes rever transações, emitir reembolsos e acompanhar pagamentos.
* **Mudar para o modo ativo / Mudar para o modo de teste** permite-te alternar entre ambientes a qualquer momento, sem afetar o código do teu projeto.
* **Gerir ligação ao Stripe** permite-te atualizar as tuas chaves de API ativas depois da configuração inicial.
* **Testar pagamentos** mostra os dados do cartão de teste como referência enquanto estás em modo de teste.

## Resolução de problemas

<AccordionGroup>
  <Accordion title="O que é um sandbox e em que difere da minha conta Stripe?">
    Um sandbox é um ambiente de teste temporário que o Macaly cria para ti. Vem com as suas próprias chaves de API de teste e permite-te simular pagamentos sem tocar em dinheiro real. **Não** é a tua conta Stripe. Quando reivindicas o sandbox, ligas-o à tua conta Stripe real. Até o reivindicares, o sandbox é anónimo e expira ao fim de 60 dias.
  </Accordion>

  <Accordion title="Os pagamentos de teste não estão a ser concluídos">
    Certifica-te de que estás a usar 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 código postal. Se o problema persistir, revê o chat para veres os detalhes do erro ou pede ao agente para diagnosticar o fluxo de pagamento.
  </Accordion>

  <Accordion title="Qual é a diferença entre o modo de teste e o modo ativo?">
    O **modo de teste** usa o ambiente sandbox com chaves de teste. Todos os pagamentos são simulados e não é envolvido dinheiro real. O **modo ativo** usa a tua conta Stripe verificada com chaves ativas. É cobrado dinheiro real, depositado na tua conta bancária. Podes mudar entre modos a qualquer momento no separador Pagamentos. Mudar de modo não afeta o código do teu projeto, apenas quais chaves Stripe estão ativas.
  </Accordion>

  <Accordion title="Não encontro as chaves de API ativas na minha Stripe Dashboard">
    Reivindicar o sandbox e verificar a tua conta Stripe são dois passos distintos. Reivindicar liga o sandbox à tua conta, mas ainda precisas de completar a verificação do negócio na Stripe (identidade, dados do negócio, conta bancária) antes de as chaves ativas serem geradas. Abre a Stripe Dashboard e segue o guia de configuração para concluíres a verificação. Se só vires chaves de teste (que começam por `pk_test_` e `sk_test_`), a tua conta ainda não foi totalmente verificada.
  </Accordion>

  <Accordion title="O Macaly continua a mostrar o modo de teste depois de eu ter verificado a minha conta Stripe">
    Verificar a tua conta Stripe não muda o Macaly automaticamente para o modo ativo. Precisas de introduzir manualmente as tuas chaves de API ativas no separador Pagamentos e depois clicar em **Mudar para o modo ativo**. O Macaly mantém-te em modo de teste até mudares explicitamente.
  </Accordion>

  <Accordion title="Os pagamentos ativos não estão a ser concluídos">
    Verifica três coisas por esta ordem:

    1. **Publicaste o teu projeto?** Os pagamentos ativos só são processados no site publicado, não na pré-visualização.
    2. **As tuas chaves estão corretas?** Confirma que introduziste a **Publishable key** (que começa por `pk_live_`) e a **Secret key** (que começa por `sk_live_`). Se colaste as chaves de teste por engano, clica em **Gerir ligação ao Stripe** e atualiza-as.
    3. **A tua conta Stripe está totalmente verificada?** Abre a Stripe Dashboard e verifica se há passos pendentes no guia de configuração. A Stripe pode exigir documentos adicionais antes de processar pagamentos ativos.
  </Accordion>

  <Accordion title="O que acontece quando o meu sandbox expira?">
    Os sandboxes não reivindicados expiram ao fim de 60 dias. Abre o separador Pagamentos e clica em **Configurar novo sandbox** para preparares um novo ambiente. O código de pagamento existente mantém-se inalterado. Se já tinhas reivindicado e verificado a tua conta Stripe, vais precisar de reintroduzir as tuas chaves ativas depois de preparares o novo sandbox.
  </Accordion>
</AccordionGroup>

## Bom saber

* **Aplicam-se as taxas da Stripe.** O Macaly não cobra taxas adicionais sobre os pagamentos. Aplicam-se as taxas de processamento padrão da Stripe a cada transação (consulta [stripe.com/pricing](https://stripe.com/pricing)).
* **Expiração do sandbox.** Os ambientes de teste não reivindicados expiram ao fim de 60 dias. Se isto acontecer, abre o separador Pagamentos e clica em **Configurar novo sandbox** para preparares um novo.
* **Os webhooks são geridos automaticamente.** O Macaly configura e mantém todos os endpoints de webhook. Não é necessária nenhuma configuração manual na Stripe Dashboard.
* **Os ambientes de teste e ativo estão isolados.** As transações de teste não aparecem na tua conta Stripe ativa, e não é feita nenhuma cobrança real.


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