Links de pagamento

O que uma fatura inclui#

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.

Nunca inclua senhas, chaves de API, dados de cartão ou códigos bancários em descrições públicas. Use um título de pedido e uma referência que o cliente reconheça.

• Nome da loja, um título de pedido de até 120 caracteres e uma descrição de até 500 caracteres.
• Valor base e uma moeda explícita USD, RUB ou USDT.
• Métodos compatíveis, taxas separadas e parcelas de IVA, uma referência de pedido e validade do link.
• As respostas do proprietário incluem link.payment com o estado salvo de uma operação existente; isso é separado do estado de disponibilidade do link.

Qualquer — o cliente escolhe#

Qualquer seleciona todos os métodos compatíveis com a moeda da fatura: cartões e Alipay para USD, SBP para RUB e cripto para USDT. A API recebe uma matriz concreta de métodos em vez da string qualquer. Cada método tem sua própria cotação.

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.

Criar um link#

1. 1

   Abra Payment links na sua conta.

2. 2

   Insira um título, valor, moeda e descrição. Defina as parcelas de taxa e IVA com os dois controles.

3. 3

   Mantenha Qualquer para deixar o cliente escolher, ou selecione métodos específicos. Defina a expiração.

4. 4

   Compare o total de cada método e visualize o checkout.

5. 5

   Receba o link de checkout pronto imediatamente após a criação e copie-o para o seu cliente ou widget.

Os termos permanecem com a fatura#

Uma fatura salva não muda quando as configurações da loja mudam. Seu preço, moeda, parcelas de taxa e IVA, referência do pedido e metadados pertencem a esse pedido. Isso mantém o total consistente para um cliente que já abriu o link.

Crie um novo link e pause o antigo quando o preço, descrição ou alocação de custos mudar. Editar o valor de uma URL não pode alterar o cálculo do servidor.

Uma página de checkout dedicada#

Os links do servidor são salvos no banco de dados e abrem em vários dispositivos em /pay/… sem acesso à conta do comerciante. Um cliente não precisa se registrar para ver uma fatura. Saldos da loja, configurações e outros registros do cliente permanecem privados.

O exemplo /pay/demo visualiza a experiência sem cobrar dinheiro. Links de demonstração no navegador são dados de teste e não devem ser apresentados como faturas reais.

Gerenciando disponibilidade#

Pausar, cancelar ou expirar um link bloqueia uma nova operação. Isso não oculta um pagamento já enviado: status, conciliação e um código bancário solicitado permanecem disponíveis. Disponibilidade do link e estado financeiro são verificados separadamente.

Retomar remove uma pausa sem alterar os termos. Cancelamento é definitivo, e um link expirado não pode ser estendido. Crie uma nova fatura para um novo pedido ou termos alterados, não para tentar novamente uma cobrança cujo resultado é desconhecido.

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.