# Conectar o Stripe

Aceite cartão nos presentes com uma conta Stripe — nova ou a que vocês já têm.

Fonte: https://docs.altaris.love/artigo/stripe/

Com o Stripe conectado, o convidado paga o presente com cartão numa página segura do próprio Stripe, e o valor entra na **conta Stripe de vocês**.

> Gateways de cartão fazem parte dos planos com essa opção — [confira o seu](https://docs.altaris.love/artigo/planos-e-cupons/). O [PIX](https://docs.altaris.love/artigo/pix-estatico/) é livre em todos.

## Antes de começar

Vocês precisam de uma conta [Stripe](https://stripe.com/br) **ativada**: cadastro completo, com cobranças habilitadas. Conta recém-criada fica em análise por um tempo, e até lá o Stripe não recebe.

Pix pelo Stripe depende de uma liberação do próprio Stripe para a conta de vocês (hoje, por convite). Sem ela, o convidado paga só com cartão — o [PIX estático](https://docs.altaris.love/artigo/pix-estatico/) do Altaris continua livre e cobre o Pix.

## O jeito fácil: conectar em um clique

Serve para quem ainda **não tem** conta no Stripe, ou prefere não mexer em chave nenhuma:

1. **Painel → Pagamentos**, botão **"Conectar com o Stripe"**;
2. O Stripe abre o cadastro: login, dados pessoais, conta bancária e verificação de identidade. Leva um tempo — pode ser feito pelo celular e retomado depois pelo mesmo botão;
3. Ao terminar, vocês voltam para o painel já conectados.

A conta criada assim é de vocês, com painel completo no Stripe, e as taxas são as do próprio Stripe.

## O jeito manual: colando a chave

Para quem já usa o Stripe. O Stripe hoje pergunta **como você vai usar a chave** e, para aplicativo de terceiros como o Altaris, só deixa criar uma **chave restrita** (`rk_live_`) — é essa que queremos, e ela é mais segura que a secreta, porque só pode fazer o que vocês autorizarem.

1. Entrem no [painel do Stripe](https://dashboard.stripe.com/login) pelo computador, no **modo de produção** (não na área restrita/sandbox);
2. Abram **Configurações (engrenagem) → Desenvolvedores → Chaves de API** e cliquem em **Criar chave restrita** (ou em **Criar chave secreta**, que leva à mesma pergunta);
3. Na pergunta "Como você usará esta chave?", escolham **"Fornecendo esta chave a um aplicativo de terceiros"** e cliquem em **Continuar com chave restrita**;
4. Em **Nome**, escrevam `Altaris Love`; em **URL**, `https://altaris.love`;
5. Marquem **"Personalize as permissões desta chave"** e acertem as seis permissões da tabela abaixo;
6. Cliquem em **Criar chave**. O Stripe pede a verificação de segurança da conta — chave de acesso (passkey), aplicativo autenticador ou o código que ele manda por e-mail/SMS. Isso é do Stripe, vale para qualquer chave de produção;
7. Copiem a chave (começa com `rk_live_`) — ela aparece **uma única vez**;
8. **Painel → Pagamentos → Conectar**, no cartão do Stripe, e então **"Prefiro colar a credencial"**. Colem e salvem: nós testamos a chave e registramos o aviso de pagamento na conta de vocês — nenhum passo extra no Stripe.

O Stripe já marca um preset para terceiros, e nele falta uma linha nossa: **Connect → Accounts**, que vem em Nenhum e precisa ficar em **Leitura**. Os nomes abaixo são os da lista, em inglês mesmo com a tela em português — a caixa **Filtrar recursos** acha cada um.

| Seção             | Recurso                               | Permissão |
| ----------------- | ------------------------------------- | --------- |
| Checkout Sessions | Checkout Sessions                     | Gravação  |
| Webhook Endpoints | Webhook Endpoints, Event Destinations | Gravação  |
| Connect           | Accounts                              | Leitura   |
| Core              | Payment Intents                       | Leitura   |
| Core              | Charges and Refunds                   | Leitura   |
| Core              | Payment Disputes                      | Leitura   |

Se quiserem uma chave enxuta, ponham em **Nenhum** todo o resto que o preset marcou — Apple Pay Domains, Balance, Balance Transaction Sources, Customers, Events, Files, Payment Method Domains, Payment Methods, Products, Setup Intents, Shipping Rates, Sources, Test Clocks e as seções Billing, Orders, Payment Links, Reporting, Tax e Terminal. Nada disso é usado pelo Altaris.

Cada permissão tem um porquê: criamos a página de pagamento (Checkout Sessions), registramos o aviso de pagamento (Webhook Endpoints), conferimos se a conta está ativada (Accounts) e lemos o desfecho de cada pagamento, inclusive estorno e contestação (Payment Intents, Charges, Disputes). Faltando alguma, o Stripe recusa a operação e o painel mostra o nome do recurso que falta — dá para voltar e editar a chave.

A chave secreta tradicional (`sk_live_`) também funciona, mas dá acesso total à conta: só vale a pena se vocês já tiverem uma em uso.

Não escolham **"Autorização de um agente de IA"**: essa marcação sujeita a chave às regras de aprovação do Stripe, e um pagamento pode ficar travado esperando alguém aprovar.

A credencial fica guardada **criptografada** e nunca aparece de novo no painel.

## Como os pagamentos chegam

O Stripe nos avisa a cada pagamento e o presente é marcado como recebido sozinho (**Painel → Pagamentos**). O convidado recebe e-mail de confirmação; o dinheiro segue os prazos e taxas do Stripe.

## Problemas comuns

- **Chave recusada**: chave de teste (`sk_test_` ou `rk_test_`) no lugar da de produção, ou conta ainda em análise no Stripe.
- **"Sem permissão" ao conectar ou ao receber um presente**: falta uma permissão na chave restrita. No Stripe, **Chaves de API → menu (⋯) da chave → Editar chave**, acertem a tabela acima e conectem de novo — não precisa criar outra chave.
- **Chave publicável**: a que começa com `pk_` é a de vitrine e não serve aqui.
- **"Conectar com o Stripe" não termina**: o cadastro pode ser retomado clicando de novo no botão — o Stripe guarda o que já foi preenchido.