Configurar Pagamentos
Este guia explica como integrar maquininha de cartão e pagamentos online (PIX, Apple Pay, Google Pay) ao sistema.
Qual opção usar?
| Situação | Recomendação |
|---|---|
| Você tem maquininha Stone | Configure o serial no PDV — pagamentos com cartão serão enviados automaticamente para a maquininha |
| Você tem maquininha ou conta Mercado Pago | Configure credenciais em Configurações — habilita PIX QR dinâmico e Carteiras Digitais (Apple Pay / Google Pay) no checkout online |
| Qualquer outra maquininha | Use o fluxo manual — o sistema registra o pagamento, mas não envia cobrança para a máquina |
Opção 1: Stone (fluxo automático)
O que acontece
Quando o atendente confirma um pagamento com cartão no PDV, o sistema envia automaticamente a cobrança para a maquininha Stone correta. O cliente insere o cartão, e o sistema é atualizado em tempo real assim que o pagamento é aprovado ou recusado.
Passo a passo
1. Peça ao administrador do sistema (quem gerencia o servidor) para configurar as credenciais Stone nas variáveis de ambiente do backend: STONE_CLIENT_ID, STONE_CLIENT_SECRET. Essas credenciais vêm do painel de desenvolvedor Stone.
2. Registre o webhook no painel Stone com a URL:
https://seu-dominio.com/api/stone/webhook3. Obtenha o serial da maquininha. O serial está impresso na etiqueta traseira da maquininha, no formato T-XXXXXXX.
4. Cadastre o serial no PDV:
- Acesse Admin → Filiais
- Edite o PDV que usa essa maquininha
- Preencha o campo Stone Terminal Serial com o serial (ex:
T-001ABC) - Salve
Pronto! A partir daí, pagamentos com cartão (crédito ou débito) naquele PDV serão enviados automaticamente para a maquininha.
O que o atendente vê
- Seleciona "Crédito" ou "Débito" no PDV → confirma
- Tela de "Aguardando pagamento..." aparece (até 60 segundos)
- Cliente insere/aproxima o cartão na maquininha
- Tela muda para "Aprovado ✓" ou "Recusado ✗" automaticamente
Opção 2: Mercado Pago (PIX online + Carteira Digital)
O que está disponível
Com as credenciais Mercado Pago configuradas, seus clientes poderão pagar online com:
- PIX QR dinâmico — QR Code gerado automaticamente, com expiração de 30 minutos
- Apple Pay / Google Pay — autenticação biométrica no dispositivo do cliente (requer Chave Pública configurada)
Passo a passo
1. Obtenha o Access Token:
- Acesse mercadopago.com.br/developers
- Vá em Credenciais → Produção
- Copie o Access Token (começa com
APP_USR-...)
2. (Para Apple Pay / Google Pay) Obtenha a Chave Pública:
- Na mesma tela de Credenciais, copie também a Chave Pública (começa com
APP_USR-..., mas é diferente do Access Token) - A Chave Pública é segura para expor ao navegador — é usada apenas para inicializar o formulário de pagamento
3. Obtenha o Device ID (opcional — apenas para maquininha Point):
- No painel do Mercado Pago, acesse a seção Point
- O Device ID é o identificador da maquininha registrada na conta
4. Configure no sistema:
- Acesse Admin → Configurações
- Role até a seção Mercado Pago Point
- Preencha Access Token (obrigatório) e, se desejar carteiras digitais, Chave Pública (Public Key)
- Preencha Device ID se tiver maquininha Point
- Clique em Testar Conexão
Se a conexão for bem-sucedida, você verá o número de dispositivos encontrados na conta e a confirmação do device.
O que o cliente vê
Após configurar, o checkout online exibirá um seletor de forma de pagamento:
- PIX ⚡ — o cliente paga via QR Code ou copia o código
- Cartão 💳 — o cliente paga na maquininha ao lado (no balcão)
- 📱 Carteira (somente se Chave Pública configurada) — o cliente é direcionado para uma tela com o botão Apple Pay ou Google Pay. Ele autentica com biometria (Touch ID, Face ID, ou impressão digital) e o pedido é confirmado automaticamente.
Nota sobre kiosks: Em totens ou computadores compartilhados, os botões Apple Pay e Google Pay não aparecem porque o dispositivo não tem carteira configurada. Nesses casos, o formulário de cartão online é exibido normalmente.
Opção 3: Sem integração (fluxo manual)
Se nenhum gateway estiver configurado no PDV, o sistema continua funcionando normalmente:
- Atendente seleciona a forma de pagamento no PDV
- Usa a maquininha física manualmente
- Confirma o pagamento no sistema após aprovação
Não é necessário configurar nada para este fluxo.
Perguntas Frequentes
E se a maquininha não responder? O sistema aguarda 60 segundos. Se não houver resposta, exibe "Tempo esgotado" e oferece a opção de tentar novamente ou alterar a forma de pagamento. O pedido já foi criado no sistema — se a cobrança foi processada na maquininha mas o sistema não recebeu confirmação, verifique o histórico de pedidos e ajuste o status manualmente.
Posso usar Stone e Mercado Pago ao mesmo tempo? Sim — em PDVs diferentes. O gateway é definido por PDV (via stoneTerminalSerial). Cada filial pode ter sua própria maquininha.
O campo "Stone Terminal Serial" aceita qualquer formato? O campo é convertido para maiúsculas automaticamente. Use exatamente o serial impresso na maquininha. Se o serial estiver errado, o sistema retornará erro da API Stone.
Onde vejo se o pagamento foi processado com sucesso? Em Admin → Pedidos, a coluna "Pagamento" mostra o status (approved, declined, ou vazio para manual). O Transaction ID da Stone também é armazenado para conciliação.
Apple Pay / Google Pay aparece para todos os clientes? Não. O botão Apple Pay aparece apenas em iPhones com Safari quando o cliente tem um cartão configurado no Apple Wallet. O botão Google Pay aparece apenas em Android com Chrome quando o cliente tem Google Pay configurado. Em outros dispositivos ou navegadores, o formulário de cartão online é exibido — ou o cliente pode escolher PIX.
Qual a diferença entre Access Token e Chave Pública? O Access Token é uma credencial privada usada apenas no servidor para cobrar pagamentos — nunca deve ser exposta ao navegador. A Chave Pública é projetada para uso no frontend: ela inicializa o formulário de pagamento (Checkout Bricks) com segurança. Mesmo que o cliente veja a Chave Pública no código da página, ela não permite realizar cobranças nem acessar sua conta.