Guia de integração VwtlProxy

Antes de começar

O pagamento funciona sem cadastro e sem login no ChatGPT. A consulta GET /api/payments/config inicia automaticamente uma sessão privada de pagamentos no navegador quando necessário. O cookie é exclusivo do host, usa HttpOnly, Path=/, SameSite=Strict e expira no navegador após 30 dias. Em HTTPS ele também usa Secure e o prefixo __Host-; o preview HTTP local usa um nome sem prefixo e sem Secure.

O navegador envia o cookie nas requisições à mesma origem. O servidor autoriza somente os pedidos e o saldo dessa sessão. O segredo de sessão tem 32 bytes aleatórios; o banco armazena apenas seu identificador derivado por hash e não o segredo. O e-mail de contato não autentica uma pessoa nem libera pedidos de outra sessão.

Se a hospedagem já fornecer uma identidade autenticada legada do ChatGPT, ela tem prioridade para preservar o histórico dessa conta. Os pedidos antigos não são migrados nem expostos à sessão anônima. Visitantes não precisam dessa identidade para comprar ou recarregar.

Os pedidos POST usam Content-Type: application/json e a origem é validada pelo servidor. O formulário visual de cadastro não cria conta, senha de acesso ou chave de API. A sessão de pagamentos é criada pela configuração, independentemente desse formulário.

E-mail de contato e ativação

O campo contactEmail é obrigatório em toda nova cobrança de compra ou recarga. A tela solicita esse e-mail antes de criar a cobrança e exibir o QR code. Informe o endereço para contato e envio dos dados de ativação do pedido.

O servidor valida o formato, rejeita caracteres de controle e quebras de linha, remove espaços nas extremidades e converte o endereço para minúsculas. O endereço normalizado tem no máximo 254 caracteres. E-mail ausente ou malformado retorna HTTP 422 com o código invalid_contact_email, antes de gerar as instruções da cobrança.

O e-mail normalizado fica no pedido, no histórico e no snapshot da fila de preparação. Ele também participa da idempotência: repetir o mesmo pedido com a mesma chave e o mesmo e-mail normalizado recupera a cobrança original; trocar o e-mail mantendo a chave gera conflito HTTP 409.

Esse contato não autentica o cliente nem concede acesso a pedidos. A autorização usa a sessão privada de pagamentos do navegador ou a identidade legada já disponível na hospedagem. A implementação não envia e-mail automaticamente; o contato e a ativação dependem do atendimento da equipe. Pedidos antigos sem contactEmail permanecem disponíveis para consulta e verificação.

Criar a cobrança no navegador

Exemplo para execução dentro do site. Inicie a sessão de pagamentos pela configuração antes de criar a cobrança. O navegador recebe o cookie e envia a origem automaticamente; não é necessário fazer login.

const config = await fetch('/api/payments/config', {credentials: 'same-origin'});
if (!config.ok) throw new Error('Configuração indisponível');
// O cookie HttpOnly de pagamentos é recebido e enviado pelo navegador.
const response = await fetch('/api/payments/invoices', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    kind: 'purchase', planId: '2gb', productType: 'dynamic',
    quantity: 1, methodId: 'eth-ethereum',
    contactEmail: 'customer+activation@example.test',
    idempotencyKey: crypto.randomUUID()
  })
});
const invoice = await response.json();
if (!response.ok) throw new Error(invoice.error?.message || 'Pagamento indisponível');
// A carteira exige a confirmação do cliente antes de enviar fundos.
// Depois do envio, registre o hash retornado pela carteira na rota /transaction.
console.log(invoice.subtotalCents, invoice.feeCents, invoice.totalCents);

Enviar e acompanhar

1. Consulte os métodos disponíveis em /api/payments/config.
2. Crie a cobrança com um método disponível e uma chave de idempotência própria.
3. Confira moeda, rede, endereço completo, quantidade exata, total e prazo.
4. Nos métodos automáticos, use a transactionRequest retornada pelo servidor no botão Pagar com MetaMask. Ela inclui a referência única que vincula a transferência ao pedido.
5. Após a carteira retornar o hash, registre {"txid":"hash retornado pela carteira"} na rota de transação.
6. Consulte o pedido para acompanhar as confirmações. Mostre sucesso somente quando status estiver paid.

Uma transferência realizada copiando somente o endereço ou QR pode não conter a referência e exige conferência pelo suporte. Bitcoin, Solana, Tron e Stellar usam conferência manual. Informar um hash sozinho não comprova recebimento nem muda o pedido para pago.

Não altere chainId, to, value ou data de transactionRequest. A carteira acrescenta o remetente e exige a confirmação do cliente. Não envie novamente enquanto uma transação estiver em processamento.

Registre o hash em POST /api/payments/invoices/{id}/transaction. Consulte GET /api/payments/invoices/{id}; a tela de checkout atual consulta a cada 20 segundos quando há transação automática registrada. Falha de consulta não representa pagamento aprovado.

Valores do exemplo

Todos os valores em USD usam centavos inteiros. A taxa de conversão é de 4,99% sobre o subtotal, com arredondamento para centavos. A taxa da blockchain é separada e paga pelo remetente. A referência de preço é US$15,99 por GB; o plano de 2 GB aplica desconto de 10% e usa US$14,39 por GB. Dinâmico e móvel têm a mesma tabela. 1 TB = 1.000 GB.

Interpretação do resultado

Transações incorretas, revertidas, com valor insuficiente ou sem referência não devem liberar a compra. O prazo do pagamento é distinto do prazo de entrega. Se já enviou fundos e a cotação expirou, contate o suporte antes de pagar novamente.

Integrações disponíveis

Esta documentação descreve os recursos de pagamento implementados na VwtlProxy. A API de fornecimento, extração, renovação e entrega de proxies ainda depende de integração com o fornecedor e não está disponível nestas rotas. A confirmação do pagamento coloca uma compra na fila de preparação; não produz credenciais de proxy automaticamente.

Pagamentos de compra confirmados exibem o prazo de 1 a 24 horas para disponibilização dos proxies. Como nossos servidores são chineses, pode ocorrer demora na entrega e na resposta do suporte. Dúvidas: support@vwtlproxy.com.

Veja a documentação da API de pagamentos e o contrato de referência.