Pular para o conteúdo principal

Introdução

Crie sessões de pagamento e acompanhe transações através dos gateways configurados em seu projeto.

Mais informações sobre pagamentos no painel de administração do OneEntry: https://doc.oneentry.cloud/docs/category/payments

🎯 O que este módulo faz?​

O módulo Payments permite que você crie sessões de pagamento e acompanhe transações para sua loja. Você configura contas de pagamento no painel de administração (Payments > Accounts) — Stripe ou personalizado — e este módulo cria uma sessão de pagamento para um pedido, retorna o link de checkout do gateway e permite que você leia o histórico e o status da sessão.

O SDK busca contas de pagamento e cria sessões de pagamento; contas e status são configurados no painel de administração.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Crie uma sessão de pagamento para um pedido e redirecione o cliente para o gateway (autenticação necessária):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Conceitos Chave​

O que é uma sessão de pagamento?​

Uma sessão de pagamento (ISessionEntity) é um registro contendo:

  • type — 'session' ou 'intent'
  • status — string de status de pagamento em formato livre (ex.: "waiting", "completed")
  • paymentAccountId — a conta configurada utilizada
  • orderId — o pedido associado
  • paymentUrl — link de checkout do gateway (ou null)
  • createdDate / updatedDate — timestamps

Tipos de sessão​

TipoDescrição
sessionCria uma página de checkout do Stripe com um link de pagamento redirecionado
intentCria uma intenção de pagamento para processamento de pagamento direto/personalizado

Tipos de conta​

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

Status de pagamento​

O status de uma sessão é uma string em formato livre definida a partir do resultado do gateway, não um enum fixo. Valores comuns:

StatusSignificado
waitingSessão criada, aguardando pagamento
completedPagamento confirmado pelo gateway

Você não pode criar ou modificar status de pagamento no painel de administração. No entanto, você pode mapear status de pagamento para status de armazenamento de pedidos, de modo que o status do pedido seja atualizado automaticamente quando o status de pagamento mudar.

Ciclo de vida do pagamento​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 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 — crie e edite-as no painel de administração do OneEntry (Payments > Accounts), fornecendo Nome, Tipo (Stripe ou Custom) e Token. Para contas Stripe, você também configura Success URL, Cancel URL e Session lifetime. O SDK é para buscar contas e criar sessões.

Sincronização de status​

Os status de pagamento são mapeados para os status de armazenamento de pedidos no painel de administração (Payments > Statuses → selecione o armazenamento de pedidos → mapeie os status → salve). Isso permite atualizações automáticas do status do pedido quando o status de pagamento muda.

Nunca armazene dados brutos do cartão​

Nunca armazene números de cartões de crédito, CVV ou datas de validade completas. O pagamento é tratado pelo gateway (Stripe), que mantém você fora do escopo para armazenar dados do cartão; o OneEntry nunca armazena detalhes brutos do cartão.

Reembolsos estão no módulo de Pedidos​

O módulo Payments não possui métodos de reembolso. Os reembolsos são tratados pelo módulo de Pedidos através de createRefundRequest(), cancelRefundRequest() e getRefunds().

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getAccounts() 🔐Obter todas as contas de pagamentoListar contas de pagamento configuradas
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)Ver 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 com Stripe?​

Crie uma conta de pagamento no painel de administração com o tipo "Stripe", em seguida, configure Success URL, Cancel URL e Session lifetime. Use createSession() com o tipo "session" para gerar um link que redirecione os clientes para o Stripe Checkout.

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 várias contas de pagamento?​

Sim. Crie várias contas de pagamento (Stripe ou custom) no painel de administração. Cada pedido pode usar uma conta diferente através de seu paymentAccountIdentifier.

Como faço para vincular status de pagamento a status de pedidos?​

No painel de administração, vá para Payments > Statuses, selecione seu armazenamento de pedidos e mapeie os status de pagamento para os status de pedidos. Isso permite a sincronização automática.

Como faço para emitir um reembolso?​

Reembolsos não fazem parte do módulo Payments. Use o módulo de Pedidos: createRefundRequest() para solicitar um reembolso, cancelRefundRequest() para cancelar uma solicitação e getRefunds() para listá-los.

🎓 Melhores Práticas​

  • Autentique-se primeiro — cada método de Payments requer um usuário autorizado (veja AuthProvider).
  • Redirecione para paymentUrl após criar uma sessão e trate as URLs de retorno do gateway em seu aplicativo.
  • Leia o status da sessão, não do cliente — verifique o status da sessão (ou getSessionByOrderId()) para confirmar o pagamento.
  • Mapeie os status de pagamento para os status de pedidos para que o estado do pedido permaneça sincronizado automaticamente.
  • Teste com chaves de teste do Stripe antes de ir para a produção.

🔗 Documentação Relacionada​