Pagamentos e statuses
Uma fatura descreve um pedido. Um pagamento é uma tentativa específica de pagá-lo. Uma tentativa de pagamento e a disponibilidade de seu link são estados separados.
Nesta página
O registro de pagamento#
A fatura armazena os termos do pedido; o pagamento identifica sua operação no gateway. O primeiro lançamento reserva um vínculo durável e uma chave de idempotência do servidor. Após o início do envio, outro método não pode criar uma segunda cobrança na mesma fatura.
GET /api/payment-links e GET /api/v1/payments retornam link.payment ao proprietário. O status ativo/pausado/cancelado/expirado do link é separado do estado do pagamento. Um cliente só pode ler sua operação por meio do token aleatório de checkout.
| Dados | Finalidade |
|---|---|
| Identificador e pedido | Associar a tentativa a uma compra |
| Valor base e moeda | A base de cálculo |
| Método de pagamento | Taxa e imposto aplicáveis |
| Contribuinte de IVA | Quem cobre o imposto |
| Taxa, IVA e totais | Cálculo salvo |
| Status e hora | Estado atual da transação |
| Referência do evento do gateway | Fonte de confirmação do servidor |
Estados operacionais ao vivo#
A demonstração usa registros de teste separados. Alterar um estado de demonstração não confirma um pagamento real nem altera registros financeiros.
| Status | Significado |
|---|---|
| pendente | Operação criada; aguardando ação ou resultado |
| requires_action | Um código bancário ou confirmação do cliente é necessário |
| processing | O provedor ainda está confirmando o resultado |
| bem-sucedido | O servidor verificou o pagamento exato |
| falhou | A tentativa terminou sem pagamento confirmado |
| expired | Instruções expiradas; a conciliação permanece disponível |
| review_required | Revisão adicional é necessária; não pague novamente |
| partially_paid | Apenas parte do valor foi recebida; não crie outro pagamento |
| partially_refunded | Parte do pagamento foi reembolsada |
| refunded | Reembolso confirmado |
| disputed | A operação está em disputa |
A fonte da verdade#
Um webhook assinado aciona uma leitura autenticada da operação exata do gateway. IDs, pedido, moeda, método, valores base e final, modo ao vivo e versão monotônica são validados. Somente o nome de um evento recebido não é prova de dinheiro.
Estado, recibo e evento do comerciante são confirmados atomicamente. Respostas mais antigas não podem sobrescrever uma versão mais nova; duplicatas não cumprem duas vezes, e pendente não pode substituir um pagamento confirmado. Esses registros não criam automaticamente um saldo sacável ou um pagamento.
Quando o resultado é desconhecido#
- 1
Mantenha a fatura original e o identificador da operação.
- 2
Leia GET /api/checkout/{token}/status; isso não cria uma cobrança.
- 3
Use POST /api/checkout/{token}/reconcile quando a conciliação explícita for necessária.
- 4
Não altere método, valor ou chave de idempotência após um resultado incerto.
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.