API de links de pagamento e chaves de API

Uma solicitação de servidor retorna um link pronto#

POST /api/v1/payments e /api/v1/payment-links criam o mesmo tipo de fatura. O nome da rota payments não implica uma cobrança: o resultado são termos de fatura persistidos e um checkoutUrl para o cliente.

Envie Authorization: Bearer <key>, Content-Type: application/json e Idempotency-Key. As chaves de idempotência contêm 16–100 letras, dígitos, hífens ou sublinhados. Persista uma chave para cada criação lógica de pedido.

curl 'https://kevmi.maxeevmax1.chatgpt.site/api/v1/payments' \
  -H "Authorization: Bearer $KEVMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-create-v1' \
  --data '{"title":"Design project · order 1042","description":"One-time payment for the agreed design work","amountMinor":500,"currency":"USD","methods":["card","alipay"],"vatCustomerPercent":100,"feeCustomerPercent":0,"orderId":"order-1042","metadata":{"campaign":"autumn"}}'

Escopos e expiração de chaves de API#

Crie uma chave em /account#keys na sua conta de comerciante verificada. O valor completo aparece uma única vez; apenas um hash é armazenado. As chaves duram 90 dias por padrão, com uma vida útil permitida de 1–365 dias e até dez chaves ativas por conta.

Conceda apenas os escopos necessários. Revogação ou expiração interrompe o acesso. Uma chave não substitui a sessão do navegador para configurações de conta, administração de endpoints, aplicativos ou moderação. Mantenha-a fora de widgets, URLs, repositórios públicos e mensagens de suporte.

O site usa /api/payment-links com seu cookie de sessão, Origin exato e X-CSRF-Token. Essas rotas operam nas mesmas faturas de propriedade da conta.

Any e métodos de API concretos#

Any é um modo de seleção de interface. Novas faturas aceitam métodos: ["card", "alipay"] ou um subconjunto não vazio para USD; ["sbp"] para RUB; ["crypto"] para USDT. O valor any não é um método de pagamento da API.

Para uma nova fatura na interface, USD oferece cartões e Alipay; RUB oferece SBP; USDT oferece criptomoeda. A API também pode salvar USD + criptomoeda para compatibilidade, mas seu pagamento cripto ao vivo é bloqueado com crypto_requires_usdt. USD e USDT são distintos, sem conversão automática nem taxa presumida de 1:1. Um pagamento cripto exige uma fatura USDT separada.

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.

Campos e termos persistidos#

A fatura salva o nome do comerciante, preço, moeda, métodos, ambas as participações de custo e cotações calculadas. Metadados são retornados ao proprietário e em eventos de servidor, mas não por meio do checkout público. Não armazene segredos de pagamento neles.

Se as participações forem omitidas, o comerciante cobre a taxa; o IVA herda vatPayer ou a configuração da conta. Uma alocação parcial pode retornar vatPayer=shared. O título, orderId e descrição são públicos.

Tente novamente após um erro de rede#

A criação inicial retorna 201 com replayed=false. A mesma chave e corpo canônico retornam 200, o checkoutUrl original e replayed=true. Uma solicitação diferente sob essa chave retorna 409 IDEMPOTENCY_CONFLICT.

Não gere outra chave após um tempo limite. Repita a solicitação original com campos idênticos. Valores omitidos não herdam novamente configurações alteradas. orderId ajuda a correlacionar um pedido, mas não substitui Idempotency-Key e não precisa ser único no armazenamento.

Leitura e paginação#

GET /api/v1/payments retorna links e nextCursor; GET /api/v1/payments/{id} retorna um link próprio. invoices:read é obrigatório. O tamanho padrão da página é 30; limit aceita 1–100.

As respostas de GET lista e detalhe incluem link.payment: um resumo da operação relacionada, ou null quando não existe operação. As respostas de POST/PATCH podem omiti-lo; leia a fatura novamente quando precisar do resumo. O status do link descreve separadamente se um novo pagamento pode começar. Campos de cartão e chaves privadas nunca são incluídos.

Passe nextCursor sem alterações por URLSearchParams. null marca o fim; IDs desconhecidos e de outros comerciantes retornam 404.

GET /api/v1/payments?limit=30
Authorization: Bearer <server-side key>

Pausar, retomar e cancelar#

PATCH /api/v1/payments/{id} com invoices:write aceita apenas {"status":"active"}, {"status":"paused"} ou {"status":"cancelled"}. O cancelamento é definitivo. expired é derivado do tempo de expiração; uma fatura expirada não pode ser estendida.

Preço, participações de custo, descrição, orderId, metadados e expiração são imutáveis. Crie outra fatura para termos diferentes. Alterar a disponibilidade emite invoice.updated, não um evento de pagamento bem-sucedido.

A resposta do cliente#

GET /api/checkout/{token}?method=card retorna a fatura pública, cotação, disponibilidade de método e operação existente. Metadados, segredos e saldos do proprietário não são expostos.

POST /api/checkout/{token}/pay exige o Origin do site e um método concreto. Dados de cartão são aceitos apenas como lacrados: {intent,jwe}, depois que o navegador obtém /card-intent. Códigos bancários são criptografados e enviados por /code. Crypto usa uma fatura USDT salva e um par moeda/rede disponível.

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.

Uma conexão ao vivo ausente retorna GATEWAY_NOT_CONNECTED; uma alocação incompatível nunca é substituída por outro cálculo. Status e reconcile leem a operação original sem uma cobrança duplicada.

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.