Introdução
🎯 O que este módulo faz?
O módulo Payments permite que você gerencie o processamento de pagamentos e transações para sua loja de e-commerce. Trabalhar com pagamentos e transações é uma parte importante de qualquer projeto de e-commerce. Ele se integra a gateways de pagamento como Stripe para lidar com sessões de pagamento, rastreamento de transações e gerenciamento de status de pagamento.
Pense nisso como seu sistema de gerenciamento de pagamentos - você configura contas de pagamento no painel de administração do OneEntry (Payments > Accounts), cria várias contas para diferentes tipos de pagamentos, como conectar um sistema de pagamento ou adicionar pagamentos em dinheiro, e este módulo cuida da criação de sessões de pagamento, rastreamento de status e gerenciamento de transações.
📖 Explicação Simples
Toda aplicação de e-commerce precisa de processamento de pagamentos seguro:
- 💳 Aceitar Pagamentos - Cartões de crédito, cartões de débito, carteiras digitais
- 🔒 Processamento Seguro - Manipulação de pagamentos em conformidade com PCI
- 🔄 Status do Pagamento - Rastrear pendentes, concluídos, falhados, reembolsados
- 💰 Reembolsos - Processar reembolsos totais ou parciais
- 📊 Histórico de Pagamentos - Visualizar todas as transações
- 🔗 Integração com Gateway - Stripe, PayPal, gateways personalizados
O problema com o manuseio manual de pagamentos:
Problemas:
- 🔒 Risco de segurança - Armazenar dados sensíveis do cartão
- 📋 Conformidade PCI - Certificação cara necessária
- 💸 Sem rastreamento de reembolsos - Gerenciamento manual de reembolsos
- 🔄 Sem histórico de pagamentos - Difícil rastrear transações
A solução Payments:
Benefícios:
- 🔒 Conformidade PCI - Pagamentos seguros tokenizados
- 📊 Rastreamento de pagamentos - Histórico completo de transações
- 🔄 Reembolsos automatizados - Processamento fácil de reembolsos
- 💸 Múltiplos gateways - Stripe, PayPal, personalizado
✨ Conceitos Chave
O que é um Pagamento?
Um Pagamento é um registro de transação financeira contendo:
- Método de Pagamento - Cartão, PayPal, transferência bancária
- Valor - Valor da transação e moeda
- Referência do Pedido - ID do pedido associado
- Status do Pagamento - Pendente, concluído, falhado, reembolsado
- Detalhes do Gateway - ID da transação Stripe, referência do PayPal
- Informações do Cliente - Detalhes de cobrança
- Carimbos de Data/Hora - Datas de criação, processamento, conclusão
Tipos de Conta Disponíveis
| Tipo | Quando Usar | Configuração Necessária |
|---|---|---|
| Stripe | Conectar o sistema de pagamento Stripe ao seu projeto | Conta Stripe, URLs |
| Custom | Sistemas de pagamento alternativos ou pagamentos em dinheiro | Configuração personalizada |
Ciclo de Vida do Pagamento
1. Create payment account in admin panel
(Configure Stripe or custom account)
↓
2. Customer places order
(Order created in Orders module)
↓
3. Create payment session
(Payments.createSession(orderId, type))
↓
4. Customer redirected to payment URL
(Stripe checkout or custom payment page)
↓
5. Customer completes payment
(Payment processed by gateway)
↓
6. Payment status updated
(waiting → pending → paid/canceled/expired)
↓
7. Notification received
↓
8. Order status synchronized
(Payment status linked to order status)
Status de Pagamento
O sistema inclui quatro status de pagamento predefinidos que indicam o estado da transação sendo processada:
| Status | Significado | Quando Ocorre |
|---|---|---|
| Pendente | Estado inicial da transação | Sessão de pagamento recém criada |
| Pago | Transação concluída com sucesso | Pagamento confirmado pelo gateway |
| Cancelado | Transação foi cancelada | Cliente cancelou o pagamento |
| Expirado | Período de validade da transação terminou | Tempo limite da sessão excedido |
Importante: Nas configurações de pagamento, você não pode criar ou modificar status. No entanto, você pode vincular esses status de pagamento predefinidos aos status de armazenamento de pedidos para permitir a sincronização automática entre os sistemas de pagamento e de pedidos.
Métodos de Pagamento
| Método | Descrição | Suporte ao Gateway |
|---|---|---|
| credit_card | Visa, Mastercard, Amex | Stripe, PayPal |
| debit_card | Cartões de débito | Stripe, PayPal |
| paypal | Conta PayPal | PayPal |
| bank_transfer | Transferência bancária, ACH | Personalizado |
| apple_pay | Carteira Apple Pay | Stripe |
| google_pay | Carteira Google Pay | Stripe |
| cash_on_delivery | Pagamento na entrega | N/A |
Por que usar o módulo Payments?
| Benefício | Descrição |
|---|---|
| Conformidade PCI | Processamento seguro de pagamentos tokenizados |
| Integração com Gateway | Stripe, PayPal embutidos |
| Rastreamento de Pagamentos | Histórico completo de transações |
| Gerenciamento de Reembolsos | Reembolsos totais/parciais fáceis |
| Proteção contra Fraude | Detecção de fraudes embutida |
| 3D Secure | Suporte à autenticação SCA |
| Multi-Moeda | Suporte para várias moedas |
📋 O que você precisa saber
Contas de Pagamento são Criadas no Painel de Administração
Você não pode criar contas de pagamento via SDK - elas são criadas no painel de administração do OneEntry:
OneEntry Admin Panel → Payments → Accounts → Create Account → Fill Form → Click "Add"
Processo de Criação:
- Preencha o formulário com três campos obrigatórios:
- Nome - Identificador de string não único
- Tipo - Selecionado no dropdown: "Stripe" ou "Custom"
- Token - Identificador de string único
- Clique em "Adicionar" para criar a conta
Gerenciamento de Conta:
- Edição - Selecione a conta, clique no ícone de editar, modifique nome/tipo/token/parâmetros do Stripe
- Ocultar - Clique no ícone de olho para ocultar contas das seleções de configuração de armazenamento de pedidos
- Exclusão - Selecione a conta, clique no ícone de excluir, confirme a remoção
O SDK é para buscar contas de pagamento e criar sessões de pagamento, não para gerenciar contas.
Tipos de Conta de Pagamento
Dois tipos de conta de pagamento estão disponíveis:
| Tipo | Descrição |
|---|---|
| Stripe | Escolha este tipo para conectar o sistema de pagamento Stripe |
| Custom | Para sistemas de pagamento alternativos ou pagamentos em dinheiro |
Configuração específica do Stripe:
- URL de Sucesso - URL de redirecionamento após pagamento bem-sucedido
- URL de Cancelamento - URL de redirecionamento se o pagamento for cancelado
- Tempo de vida da sessão - Tempo limite da sessão em minutos
Sincronização de Status de Pagamento
Os status de pagamento podem ser vinculados aos status de armazenamento de pedidos:
OneEntry Admin Panel → Payments → Statuses → Select Order Storage → Map Statuses → Save
Fluxo de trabalho de mapeamento de status:
- Navegue até a subseção Status dentro de Payments
- Selecione o sistema de armazenamento de pedidos desejado
- Mapeie cada status de pagamento predefinido para o valor correspondente do status de armazenamento de pedidos
- Verifique se todos os mapeamentos estão corretos
- Clique em Salvar para aplicar as alterações
Isso permite atualizações automáticas de status nos registros de pedidos quando os status de pagamento mudam.
Nunca Armazene Dados Brutos do Cartão
CRÍTICO: Nunca armazene números de cartões de crédito, CVV ou datas de validade completas.
Por quê?
- A conformidade com PCI DSS exige manuseio seguro
- Armazenar dados do cartão expõe você a responsabilidades
- O OneEntry nunca armazena detalhes brutos do cartão
💡 Notas Importantes
Contas de Pagamento são Criadas no Painel de Administração
Lembre-se: O SDK é para buscar contas de pagamento e criar sessões, não para criar contas.
Para criar/editar contas de pagamento: Use o Painel de Administração do OneEntry.
Gerenciamento de Conta de Pagamento
Criando contas no painel de administração:
- Navegue até Payments > Accounts
- Preencha o formulário com Nome, Tipo e Token
- Para contas Stripe, configure a URL de Sucesso, URL de Cancelamento e Tempo de Vida da Sessão
- Clique em "Adicionar" para criar
Gerenciando contas:
- Editar - Modifique nome, tipo, token ou parâmetros específicos do Stripe
- Ocultar - Clique no ícone de olho para ocultar do armazenamento de pedidos (não exclui)
- Excluir - Remova contas não utilizadas completamente
Importante: Apenas contas não utilizadas podem ser excluídas.
Configuração de Status de Pagamento
Importante: Você não pode criar ou modificar status de pagamento no painel de administração. O sistema possui quatro status predefinidos: Pendente, Pago, Cancelado, Expirado.
Fluxo de trabalho de sincronização de status:
- Navegue até Payments > Statuses
- Selecione o sistema de armazenamento de pedidos
- Mapeie os status de pagamento predefinidos para os status de armazenamento de pedidos
- Clique em Salvar para aplicar as alterações
Isso permite atualizações automáticas de status de pedidos quando os status de pagamento mudam.
Tipos de Sessão
Dois tipos de sessão estão disponíveis:
| Tipo | Descrição |
|---|---|
| session | Cria uma página de Checkout do Stripe com link de pagamento |
| intent | Cria uma intenção de pagamento para processamento direto de pagamento |
Segurança em Primeiro Lugar
🔒 Regras de segurança críticas:
- Nunca armazene dados brutos do cartão - Use tokenização
- Use apenas HTTPS - Todas as páginas de pagamento devem ser SSL
- Valide no servidor - Nunca confie em dados do lado do cliente
- Registre transações - Mantenha um histórico de auditoria
- Manuseie PII com cuidado - Proteja os dados do cliente
Conformidade PCI
✅ O OneEntry cuida da conformidade PCI para você:
- Processamento de pagamentos tokenizados
- Integração segura com gateway
- Sem armazenamento de dados brutos do cartão
- Transmissão criptografada
Sua responsabilidade:
- Use HTTPS nas páginas de pagamento
- Não registre dados sensíveis
- Siga as melhores práticas de segurança
Polling de Status de Pagamento
Para pagamentos assíncronos, faça polling para atualizações de status:
Limitações de Reembolso
Regras importantes de reembolso:
- Só é possível reembolsar pagamentos concluídos
- Reembolsos parciais não devem exceder o valor original
- Alguns gateways têm limites de tempo (por exemplo, 180 dias)
- Reembolsos são assíncronos (podem levar dias)
📊 Tabela de Referência Rápida
| Método | Descrição | Caso de Uso |
|---|---|---|
| getAccounts() | Obter todas as contas de pagamento | Listar métodos de pagamento disponíveis |
| getAccountById() | Obter conta de pagamento por ID | Buscar detalhes de conta específica |
| createSession() 🔐 | Criar sessão de pagamento | Gerar link de pagamento para pedido |
| getSessions() 🔐 | Obter todas as sessões de pagamento (paginadas) | Visualizar histórico de sessões de pagamento |
| getSessionById() 🔐 | Obter sessão de pagamento por ID | Verificar status de sessão específica |
| getSessionByOrderId() 🔐 | Obter sessão de pagamento por ID de pedido | Encontrar pagamento para pedido específico |
🔐 = Requer autorização
❓ Perguntas Comuns (FAQ)
Como configuro pagamentos Stripe?
Crie uma conta de pagamento no painel de administração com o tipo "Stripe", em seguida, configure a URL de Sucesso, URL de Cancelamento e Tempo de Vida da Sessão. Use createSession() para gerar links de pagamento que redirecionam os clientes para o Checkout do Stripe.
Qual é a diferença entre os tipos de pagamento session e intent?
Uma session cria uma página de Checkout do Stripe com uma URL de redirecionamento, ideal para páginas de pagamento hospedadas. Uma intent cria uma intenção de pagamento para integração de formulário de pagamento personalizado diretamente em seu aplicativo.
Posso suportar múltiplos métodos de pagamento?
Sim! Crie várias contas de pagamento (Stripe, personalizado, pagamento na entrega) no painel de administração. Cada pedido pode usar uma conta de pagamento diferente com base na seleção do cliente.
Como vinculo status de pagamento a status de pedidos?
No painel de administração, vá para Payments > Statuses, selecione seu armazenamento de pedidos e mapeie os quatro status de pagamento predefinidos (Pendente, Pago, Cancelado, Expirado) para os status de pedidos correspondentes. Isso permite a sincronização automática.
O que acontece se uma sessão de pagamento expirar?
As sessões de pagamento têm um tempo de vida configurável (definido nas configurações da conta). Se um cliente não concluir o pagamento dentro desse tempo, o status da sessão muda para "Expirado" e ele precisará criar uma nova sessão de pagamento.
🎓 Melhores Práticas
- Use tokenização - Sempre tokenize cartões com Stripe.js
- Valide valores - Verifique totais no servidor, não apenas no cliente
- Trate erros de forma elegante - Mensagens de erro claras para os usuários
- Registre transações - Mantenha um histórico de auditoria de todos os pagamentos
- Use webhooks - Ouça atualizações de status de pagamento
- Teste com chaves de teste - Use o modo de teste do Stripe antes da produção
- Manuseie 3D Secure - Implemente o fluxo de autenticação SCA
- Armazene IDs de transação - Mantenha referências de gateway para disputas
Mais informações sobre pagamentos no painel de administração do OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/payments
Definição do módulo Payments
O módulo Payments gerencia o processamento de pagamentos e transações. Ele fornece ferramentas para trabalhar com contas de pagamento, criar sessões de pagamento e rastrear status de pagamento.
const { Payments } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentação Relacionada
- Painel de Administração do OneEntry - Payments - Documentação oficial do painel de administração
- Painel de Administração do OneEntry - Contas de Pagamento - Configurar contas de pagamento
- Painel de Administração do OneEntry - Status de Pagamento - Sincronização de status
- Painel de Administração do OneEntry - Integração com Stripe - Conectar Stripe
- Módulo de Pedidos - Gerenciamento de pedidos e checkout
- Módulo AuthProvider - Necessário para autorização de sessão
- Módulo de Produtos - Produtos disponíveis para compra
- Documentação do Stripe - Integração com gateway de pagamento