Documentação whitemax

1. 1

   Crie sua conta de vendedor

   Acesse /signup, confirme seu e-mail e faça login. Você cai automaticamente no painel.

2. 2

   Gere uma chave secreta

   Em Painel → Chaves de API, clique em Nova chave, dê um nome (ex: produção) e copie o token wmx_live_.... Ele só aparece uma vez — guarde em variável de ambiente no seu servidor.

   # .env do seu site
   WHITEMAX_API_KEY=wmx_live_sua_chave_aqui

3. 3

   Crie a cobrança PIX no checkout

   Quando o cliente clicar em “Pagar com PIX”, seu backend chama POST /charges com o valor em centavos e os dados do pagador.

   // Node.js / Next.js / Express — no servidor
   const r = await fetch("https://gatewhitemax.site/api/public/v1/charges", {
     method: "POST",
     headers: {
       "Authorization": `Bearer ${process.env.WHITEMAX_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       amount: 4990,                     // R$ 49,90
       description: "Pedido #1234",
       external_id: "1234",              // seu ID interno
       customer: {
         name: "Maria Silva",
         email: "maria@exemplo.com",
         document: "12345678900",
         phone: "11987654321",
       },
     }),
   });
   const charge = await r.json();
   // charge.id          -> use para consultar o status
   // charge.pix.qrcode  -> string copia-e-cola do PIX

4. 4

   Mostre o QR Code para o cliente

   Devolva o charge.id e o charge.pix.qrcode ao frontend. Renderize o QR a partir do copia-e-cola e ofereça um botão de copiar.

   // Frontend (React) — usando a lib qrcode.react
   import { QRCodeSVG } from "qrcode.react";
   
   <QRCodeSVG value={charge.pix.qrcode} size={220} />
   <button onClick={() => navigator.clipboard.writeText(charge.pix.qrcode)}>
     Copiar código PIX
   </button>

5. 5

   Acompanhe o status da cobrança

   Enquanto o cliente vê o QR, faça polling a cada 3–5 segundos no endpoint GET /charges/{id}. Pare quando o status virar paid ou failed.

   // Frontend — pooling simples
   async function checkStatus(id) {
     const r = await fetch(`/api/whitemax-status?id=${id}`);
     return r.json(); // { status: "pending" | "paid" | "failed" }
   }
   
   const interval = setInterval(async () => {
     const { status } = await checkStatus(charge.id);
     if (status === "paid")   { clearInterval(interval); onPaid(); }
     if (status === "failed") { clearInterval(interval); onFailed(); }
   }, 4000);

   No backend desse /api/whitemax-status você chama GET https://gatewhitemax.site/api/public/v1/charges/{id} com sua chave — nunca exponha a chave no navegador.

6. 6

   Libere o produto após o pagamento

   Quando o status for paid, marque o pedido como pago no seu banco, envie o e-mail de confirmação e redirecione o cliente para a página de sucesso. Pronto — sua integração PIX está no ar. 🎉

Abaixo você encontra a referência completa de cada endpoint, campos aceitos, respostas e códigos de erro.