Integração de gateway de pagamento

Verificando disponibilidade#

A Kevmi usa a API v3 do gateway para criar e recuperar operações, ler status e reconciliar resultados. A integração suporta transporte criptografado de cartão e código bancário, pagamentos QR do Alipay e SBP, um catálogo de criptomoeda/moeda e eventos financeiros recebidos.

gateway.configured em GET /api/config informa se as configurações de conexão necessárias estão presentes. Este endpoint não testa o gateway; gateway.connected=false aqui significa que a conectividade não foi verificada. Para uma fatura específica, leia invoice.availability em GET /api/checkout/{token}: ele verifica o método, valor, termos e aprovação do comerciante. O campo de compatibilidade invoice.gatewayConnected espelha availability.available e também não é uma verificação de saúde nem uma garantia de aprovação de pagamento.

Um novo pagamento e uma intenção de cartão exigem que a solicitação mais recente de revisão do site do comerciante seja aprovada. A aprovação por si só não conecta o gateway de pagamento. Se a revisão mudar após o envio, a operação existente permanece disponível para leitura de status, conciliação e um código bancário solicitado.

Contrato de checkout do cliente#

Dados sensíveis são criptografados no navegador com RSA-OAEP-256 e A256GCM. A chave privada permanece no gateway. A Kevmi valida que a intenção pertence a esta fatura e propósito, retransmite o envelope e não armazena números de cartão em texto simples, CVV, nome do comprador, e-mail, códigos bancários ou o próprio envelope.

Instale a extensão de transporte criptografado no host do gateway antes de habilitar cartões. Ela verifica a assinatura da intenção, expiração, repetição, pedido e valores. Não há fallback em texto simples. Isso descreve o mecanismo de proteção, não a certificação PCI.

Hospedagem e conectividade do gateway#

A Kevmi oferece hospedagem de Sites no Cloudflare Workers com D1 e auto-hospedagem em Node.js com SQLite. SQLite requer volume persistente e backups. O gateway de pagamento roda como serviço separado com armazenamento durável próprio.

Um gateway externo exige uma origem HTTPS acessível pelo servidor. No pacote auto-hospedado, o servidor se conecta a um serviço de gateway fixo na rede privada do contêiner; a API do serviço de gateway não é exposta à internet. O site público e os callbacks usam HTTPS. O navegador também criptografa dados do cartão e códigos bancários antes de chegarem à Kevmi.

localhost refere-se ao servidor ou contêiner atual; não expõe o computador do proprietário do gateway. Chaves de conexão e segredos pertencem apenas à configuração do servidor.

Para um domínio personalizado, defina uma origem HTTPS pública em NEXT_PUBLIC_SITE_URL antes da compilação. Documentação, links canônicos e recursos de indexação usam esse valor. Ele aceita apenas um esquema e host com porta opcional, sem caminho, consulta, fragmento ou credenciais. Alinhe-o com APP_ORIGIN na configuração do servidor.

Cálculo e termos suportados#

As faturas do novo workspace usam um preço base em USD e o plano Any oferece todos os quatro métodos. O SBP converte para RUB à taxa de referência congelada do Banco da Rússia; cripto usa a regra explícita de fatura 1:1 USD/USDT. O preço nativo legado permanece disponível para faturas antigas e solicitações de API sem pricingMode=universal. Consulte a seção de múltiplas lojas e preço em USD abaixo.

Para um novo pagamento ao vivo com cartão ou Alipay, o gateway atual suporta apenas feeCustomerPercent=0 e vatCustomerPercent=100: o comerciante cobre toda a taxa de processamento e o IVA é adicionado integralmente para o cliente. Outras parcelas podem ser salvas e calculadas em uma fatura, mas a execução é bloqueada com unsupported_allocation. O servidor nunca altera silenciosamente os termos salvos. Pagamentos SBP e USDT cripto suportam todas as parcelas de taxa de processamento e não têm IVA.

Enviar um total_cents arbitrário não altera o cálculo de impostos do provedor. Um valor real diferente do total salvo entra em revisão e não pode confirmar o cumprimento. Campos business_balance do gateway são retidos como evidência de liquidação, não tratados como saldo de comerciante da Kevmi.

Conectando um gateway ao vivo#

Conectar o gateway inclui configuração do servidor, verificações dos canais selecionados e processamento de eventos financeiros verificados. A prontidão da configuração é verificada separadamente da conectividade do provedor. Um pagamento bem-sucedido é aceito após verificar o status e o valor da operação. As instruções de implantação estão em ops/gateway-integration.md.

1. 1

   Implante o servidor Kevmi e o gateway como serviços separados. Configure armazenamento durável, backups e os processos em segundo plano necessários.

2. 2

   Para uma conexão externa, defina uma origem HTTPS em GATEWAY_BASE_URL. O pacote auto-hospedado usa seu serviço interno configurado. Ambos exigem um GATEWAY_API_KEY somente do servidor e um GATEWAY_WEBHOOK_SECRET separado; segredos nunca chegam ao navegador.

3. 3

   Defina BACKEND_WEBHOOK_URL do gateway como /api/gateway/webhook na Kevmi e um BACKEND_WEBHOOK_SECRET correspondente.

4. 4

   Ative o transporte criptografado de cartão e mantenha sua chave privada exclusivamente no host do gateway. Verifique a disponibilidade da chave pública e as configurações correspondentes de assinatura de intenção.

5. 5

   Verifique a prontidão do canal, restrições e a aprovação do site do comerciante antes do lançamento.

Múltiplas lojas e um preço base em USD#

Escolha Todas as lojas para análises e operações agregadas, ou selecione uma loja para seus próprios registros. Cada loja tem um storeId separado, nome, padrão de IVA, faturas, chaves de API, endpoints de webhook, histórico de eventos e aplicativo de site. Notificações e tickets de suporte pertencem à conta. Uma conta pode criar até 100 lojas. Registros existentes permanecem na primeira loja.

As faturas do novo workspace usam pricingMode="universal" e um preço base em USD. O plano Any inclui cartão, alipay, sbp e cripto; um comerciante pode selecionar um subconjunto. Cartões e Alipay cobram em USD. O SBP cobra em RUB usando a taxa de referência USD/RUB do Banco da Rússia. Cripto cobra USDT sob a regra explícita de fatura 1 USD = 1 USDT. Esta é uma regra de conversão de fatura, não uma cotação de mercado de USDT. O gateway fornece a taxa da moeda selecionada, o valor exato da transferência e instruções antes da transferência.

A taxa de referência e ambos os valores são congelados na criação. Faturas que envolvem conversão RUB expiram dentro de 24 horas. Se a taxa de referência não puder ser obtida, a criação falha com FX_UNAVAILABLE; nenhuma taxa de fallback inventada ou desatualizada é usada. O valor do proprietário em minor e cotações usam a moeda contábil USD. quotes[method].settlement contém a cotação de cobrança nativa. O checkout público expõe a moeda de cobrança selecionada em currency, o preço original em baseAmountMinor/baseCurrency, e a taxa de referência em fx. Uma vez que um pagamento foi enviado, seu método não pode ser alterado; uma fatura tem uma operação de gateway.

Crie uma chave de API dentro da loja pretendida e envie Authorization: Bearer <key> do seu servidor. Seu vínculo de loja é imutável; X-Kevmi-Store não pode conceder acesso a outra loja. Sessões de navegador selecionam X-Kevmi-Store: <storeId>; omitir seleciona a primeira loja. O valor all é aceito apenas por GET /api/account/dashboard e GET /api/payment-links. Mutações exigem uma loja selecionada, Origin e X-CSRF-Token. IDs de conta e IDs de loja são identificadores diferentes.

Para compatibilidade, solicitações de API sem pricingMode="universal" mantêm preço nativo e as restrições originais de moeda. Faturas existentes nunca são recalculadas. Recibos confirmados nas análises refletem pagamentos verificados menos despesas de fatura salvas; eles não são um saldo sacável. Moedas de fatura legadas permanecem separadas e pagamentos são combinados com o suporte. Cumpra um pedido somente após verificar payment.fulfillmentReady=true e payment.status="succeeded" através da API do servidor, histórico de eventos ou um webhook assinado.