Pular para o conteúdo principal

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 pendente, concluído, falhado, reembolsado
  • 💰 Reembolsos - Processar reembolsos totais ou parciais
  • 📊 Histórico de Pagamentos - Visualizar todas as transações
  • 🔗 Integração de 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​

TipoQuando UsarConfiguração Necessária
StripeConectar o sistema de pagamento Stripe ao seu projetoConta Stripe, URLs
CustomSistemas de pagamento alternativos ou pagamentos em dinheiroConfiguração personalizada

Ciclo de Vida do Pagamento​

1. Criar conta de pagamento no painel de administração
   (Configurar conta Stripe ou personalizada)
   ↓
2. Cliente faz um pedido
   (Pedido criado no módulo Orders)
   ↓
3. Criar sessão de pagamento
   (Payments.createSession(orderId, type))
   ↓
4. Cliente redirecionado para a URL de pagamento
   (Checkout do Stripe ou página de pagamento personalizada)
   ↓
5. Cliente completa o pagamento
   (Pagamento processado pelo gateway)
   ↓
6. Status do pagamento atualizado
   (aguardando → pendente → pago/cancelado/expirado)
   ↓
7. Notificação recebida
   ↓
8. Status do pedido sincronizado
   (Status do pagamento vinculado ao status do pedido)

Status de Pagamento​

O sistema inclui quatro status de pagamento predefinidos que indicam o estado da transação sendo processada:

StatusSignificadoQuando Ocorre
PendenteEstado inicial da transaçãoSessão de pagamento recém criada
PagoTransação concluída com sucessoPagamento confirmado pelo gateway
CanceladoTransação foi canceladaCliente cancelou o pagamento
ExpiradoPeríodo de validade da transação terminouTempo 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étodoDescriçãoSuporte ao Gateway
credit_cardVisa, Mastercard, AmexStripe, PayPal
debit_cardCartões de débitoStripe, PayPal
paypalConta PayPalPayPal
bank_transferTransferência bancária, ACHPersonalizado
apple_payCarteira Apple PayStripe
google_payCarteira Google PayStripe
cash_on_deliveryPagamento na entregaN/A

Por que usar o módulo Payments?​

BenefícioDescrição
Conformidade PCIProcessamento seguro de pagamentos tokenizados
Integração de GatewayStripe, PayPal embutidos
Rastreamento de PagamentosHistórico completo de transações
Gerenciamento de ReembolsosReembolsos totais/parciais fáceis
Proteção contra FraudesDetecção de fraudes embutida
3D SecureSuporte à autenticação SCA
Multi-MoedaSuporte para múltiplas 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:

Painel de Administração do OneEntry → Payments → Accounts → Criar Conta → Preencher Formulário → Clicar "Adicionar"

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:

TipoDescrição
StripeEscolha este tipo para conectar o sistema de pagamento Stripe
CustomPara 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
  • Duração 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:

Painel de Administração do OneEntry → Payments → Statuses → Selecionar Armazenamento de Pedidos → Mapear Status → Salvar

Fluxo de trabalho de mapeamento de status:

  1. Navegue até a subseção Status dentro de Payments
  2. Selecione o sistema de armazenamento de pedidos desejado
  3. Mapeie cada status de pagamento predefinido para o valor correspondente do status de armazenamento de pedidos
  4. Verifique se todos os mapeamentos estão corretos
  5. 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:

  1. Navegue até Payments > Accounts
  2. Preencha o formulário com Nome, Tipo e Token
  3. Para contas Stripe, configure a URL de Sucesso, URL de Cancelamento e Duração da Sessão
  4. 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 da configuração de 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:

  1. Navegue até Payments > Statuses
  2. Selecione o sistema de armazenamento de pedidos
  3. Mapeie os status de pagamento predefinidos para os status de armazenamento de pedidos
  4. 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:

TipoDescrição
sessionCria uma página de Checkout do Stripe com link de pagamento
intentCria 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 de 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étodoDescriçãoCaso de Uso
getAccounts()Obter todas as contas de pagamentoListar métodos de pagamento disponíveis
getAccountById()Obter conta de pagamento por IDBuscar detalhes de conta específica
createSession() 🔐Criar sessão de pagamentoGerar 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 IDVerificar status de sessão específica
getSessionByOrderId() 🔐Obter sessão de pagamento por ID do pedidoEncontrar 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 Duração 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, personalizada, 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 aos 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 uma duração configurável (definida nas configurações da conta). Se um cliente não completar 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(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​