Integração com o Stripe

Recebimento de pagamentos online via Stripe: cartões, Apple Pay, Google Pay.

1. Visão geral#

Stripe — plataforma de pagamentos global. No diretório do Cenaly, o Stripe está disponível para integração em 46 países. A integração Cenaly + Stripe permite:

• 💳 Receber pagamentos com cartões (Visa, Mastercard, AmEx)
• 📱 Apple Pay / Google Pay — pagamento com um toque
• 💰 Receber repasses na sua conta bancária
• 🔄 Processar estornos pelo painel administrativo
• 💵 Gorjetas — o cliente adiciona gorjeta ao pagar
• 📊 Relatórios — análise financeira completa

2. Requisitos#

• ✅ Conta Cenaly (o pagamento online está disponível em qualquer plano, incluindo o gratuito)
• ✅ Conta Stripe (cadastro gratuito em stripe.com)
• ✅ Conta bancária para receber os repasses (na moeda do seu país)
• ✅ Documentos para verificação (passaporte / ID, documentos da empresa)

Países compatíveis#

O Stripe está disponível para integração em 46 países:

3. Criação da conta Stripe#

Etapa 1. Cadastro#

1. Acesse stripe.com → Start now
2. Informe o email e crie uma senha
3. Confirme o email

Etapa 2. Verificação do negócio#

O Stripe solicitará:

A verificação costuma levar 1–3 dias úteis.

Etapa 3. Obtenha as chaves de API#

1. No painel do Stripe: Developers → API keys
2. Copie:
   • Publishable key (pk_live_...)
   • Secret key (sk_live_...)

4. Integração com o Cenaly#

É integrada a sua própria conta Stripe: o dinheiro do cliente vai diretamente para o seu saldo no Stripe, o Cenaly não o retém.

Abra Loja de aplicativos → categoria "Finanças" → cartão do Stripe → "Configurar" — o bloco de integração abrirá em um modal direto na loja. O caminho de sempre também funciona: Unidades → cartão da unidade → aba "Pagamentos" (seção "Pagamento do cliente"), botão "Integrar" no cartão do Stripe.

Assistente de integração (recomendado)#

O assistente passo a passo (≈10 minutos) conduz por todo o processo, mostrando onde clicar no painel do Stripe:

1. Escolha o modo — de teste ou de produção. O modo no Stripe e o seletor "Teste / Produção" no Cenaly devem coincidir.
2. Copie as chaves — Developers → API keys: a Secret key (sk_test_… / sk_live_…) é obrigatória, a Publishable key (pk_…) é opcional.
3. Adicione o webhook — Developers → Webhooks → Add endpoint, e no campo Endpoint URL cole o endereço do webhook do Cenaly, que o assistente fornece com o botão "Copiar". Sem o webhook, o Stripe não informará que o pedido foi pago, e o pedido pode permanecer com o status "aguardando".
4. Selecione os eventos — no bloco "Select events", adicione obrigatoriamente checkout.session.completed (é ele que confirma o pagamento do pedido) e, para formas de pagamento diferidas, também checkout.session.async_payment_succeeded e checkout.session.async_payment_failed. Depois, clique em "Add endpoint". Sem esses eventos, o webhook é criado, mas não informará sobre o pagamento.
5. Copie o Webhook signing secret (whsec_…) — campo opcional, mas com ele a verificação da assinatura das notificações é ativada.
6. Integrar — os valores informados vão para um backend protegido.

Formulário curto#

Se você já sabe onde fica cada coisa no Stripe, abra o formulário de integração inline e preencha os mesmos campos: Secret key, Webhook signing secret (opc.), Publishable key (opc.) e o seletor de modo.

5. Configuração dos métodos de pagamento#

Cartões bancários#

Ativados automaticamente ao conectar o Stripe:

• Visa / Mastercard — todos os países
• American Express — a maioria dos países
• Diners Club / Discover — seletivamente

Apple Pay e Google Pay#

Não há botões separados no Cenaly para eles: o pagamento acontece na página hospedada do Stripe Checkout, por isso as carteiras são ativadas do lado do Stripe.

• Google Pay — funciona logo após conectar o Stripe (Android, Chrome).
• Apple Pay — o Stripe exige confirmar o domínio: Settings → Payment methods → Apple Pay → Add new domain. Após a verificação, o botão aparecerá no iOS/Safari.

Outros métodos#

Pelo Stripe Dashboard, você pode ativar:

Ative os métodos desejados no Stripe Dashboard → Settings → Payment methods.

6. Gorjetas#

Configuração#

1. Unidades → cartão da unidade → aba «Geral» → botão «Gorjetas».
2. Como funciona:

Como o cliente vê isso#

Ao pagar, após escolher os pratos:

Seu pedido: 45₾

Adicionar gorjeta?
[ 10% (4.50₾) ] [ 15% (6.75₾) ] [ 20% (9.00₾) ] [ Outro valor ]
[ Sem gorjeta ]

TOTAL: 49.50₾   [Pagar →]

Relatórios de gorjetas#

Seção Finanças:

• aba «Visão geral» — valor total de gorjetas no período com comparação ao anterior;
• aba «Vendas» — gorjetas por garçom.

7. Repasses para a sua conta#

Como o Stripe paga o dinheiro#

O cliente paga → o Stripe retém → Após T+2 dias → Dinheiro na sua conta

Configuração do cronograma#

No Stripe Dashboard → Settings → Payouts:

• Diariamente (recomendado)
• Semanalmente (dia específico da semana)
• Mensalmente

8. Taxas do Stripe#

9. Estornos#

O estorno de dinheiro via Stripe é iniciado em dois lugares — depende de como o pedido foi atendido.

Estornos da loja online (RMA)#

1. Seção Estornos → cartão da solicitação.
2. Escolha o modo de estorno: no método de pagamento original (Stripe), com vale-presente (store credit) ou por troca.
3. Marque os itens (estorno total ou parcial) e decida se o produto volta ao estoque.
4. O dinheiro sai direto da página; no cartão do cliente, costuma chegar em 5–10 dias úteis.

Estornos no caixa#

No POS, o estorno é feito pelo recibo — total ou parcial, e também há troca com revenda. O turno de caixa precisa estar aberto.

No cartão do pedido, na seção Pedidos, aparecem os selos dos estornos feitos com link para a solicitação.

10. Segurança#

PCI DSS#

• O Cenaly não armazena dados de cartões — tudo é processado pelo Stripe
• O Stripe é certificado como PCI Level 1 (nível mais alto)
• Os dados dos cartões são criptografados e tokenizados

3D Secure#

• Verificação automática de 3D Secure para cartões da UE (SCA/PSD2)
• Reduz fraudes e chargebacks
• Para o cliente: confirmação no aplicativo do banco

Radar (proteção contra fraudes)#

O Stripe Radar bloqueia automaticamente transações suspeitas:

• Padrão de compras incomum
• Cartões de listas negras
• Anomalias de geolocalização

11. Testes#

Antes de ativar em produção, teste:

Cartões de teste do Stripe#

CVV: quaisquer 3 dígitos. Data: qualquer data futura. ZIP: qualquer um.

Como testar#

1. Ao conectar, selecione o botão «Modo de teste» (cada provedor tem o seu).
2. Use as chaves de teste (pk_test_..., sk_test_...) — e o webhook criado no mesmo modo de teste do Stripe.
3. Faça um pedido de teste → pague com um cartão de teste.
4. Verifique o status do pedido na seção Pedidos — deve ficar «Pago».
5. Quando tudo funcionar — reconecte o provedor com as chaves de produção no modo «Produção».

12. Provedores alternativos#

Para países sem Stripe ou como complemento — já prontos para conectar:

Outros 94 provedores (Adyen, PayTR, ЮKassa, LiqPay, Mercado Pago, Razorpay e outros) já estão na lista, mas aparecem em cinza — a integração ainda está em testes. Visão completa — na seção Pagamento.

Conexão de qualquer provedor: Loja de aplicativos → categoria «Finanças» → card do provedor → «Configurar», ou pelo caminho habitual Unidades → card da unidade → aba «Pagamentos».

13. Perguntas frequentes#

Quando vou receber o dinheiro?#

Em 2 dias úteis após o pagamento (T+2). O primeiro repasse pode levar de 7 a 14 dias (enquanto o Stripe verifica a conta).

O hóspede quer pagar em dinheiro — como proceder?#

Os métodos «em dinheiro» e «cartão na entrega» estão sempre disponíveis e não exigem um provedor de pagamento — o hóspede os escolhe no checkout, e o caixa realiza a cobrança. O Stripe não é acionado nesse caso; o recibo é emitido no caixa, se você tiver equipamento fiscal conectado (veja Fiscalização).

É possível conectar tanto o Stripe quanto o BOG iPay?#

Sim. Na aba «Pagamentos» é possível ativar vários provedores ao mesmo tempo — no checkout o hóspede verá um botão para cada um, identificado com o nome do provedor.

O Stripe bloqueou a conta — o que fazer?#

1. Verifique o email — o Stripe envia o motivo
2. Normalmente é necessária uma verificação adicional
3. Entre em contato com o Stripe Support: support.stripe.com
4. Durante o bloqueio, é possível usar um provedor alternativo

Como minimizar a taxa?#

• Incentive o pagamento com cartões EU (1,5% em vez de 2,9%)
• Use SEPA para valores altos (0,35€ fixo)
• Com um volume alto (>100K€/mês) — solicite ao Stripe um plano individual

14. Suporte#

• Stripe: support.stripe.com
• Cenaly: support@cenaly.com → assunto «Stripe / Pagamento»
• Stripe Status: status.stripe.com (verificação de funcionamento)