Integre a KlausPay usando IA

Instruções para o modelo (obrigatório)

1. Não invente rotas. Use apenas os endpoints documentados aqui, na base https://api.klauspay.com. [URL da API — confirmar]
2. Segredos só no servidor. A Secret Key nunca vai para o browser, bundle frontend ou repositório público.
3. Valores em centavos. amount_cents: 9900 = R$ 99,00. Moeda em ISO 4217 (BRL, USD, EUR).
4. Modelo non-custodial. A liquidação ocorre no gateway do vendedor (Stripe/Asaas/Woovi). A KlausPay não retém saldo — apenas orquestra o checkout e emite eventos.
5. Idempotência. Envie Idempotency-Key em toda criação crítica (checkout, sessão).
6. Materialize o pedido antes do pagamento. Crie o pedido interno com status pending e guarde o checkout_id como referência ANTES de confirmar o pagamento.
7. Confie no webhook + reconciliação. Trate o webhook checkout.paid como fonte de verdade e implemente um job de reconciliação como fallback.

URLs oficiais

Conceitos-chave

• Checkout: a sessão de pagamento criada pela API. Retorna uma URL hospedada e/ou um token para o front. Contém valor, moeda, produto e dados do comprador.
• Gateway conectado: a conta do vendedor no Stripe, Asaas ou Woovi onde o dinheiro é efetivamente processado e liquidado.
• Evento (webhook): notificação HTTP enviada pela KlausPay ao seu backend quando algo muda (pago, reembolsado, estornado).
• Liberação de acesso: ação do seu sistema (ou da área de membros da KlausPay) ao receber checkout.paid.

Autenticação

Integrações server-side autenticam com um par API Key + Secret, gerado no painel em Configurações → API. Envie ambos como cabeçalhos. A Secret Key nunca deve aparecer no frontend.

X-API-Key: kp_pub_xxxxxxxxxxxx
X-API-Secret: kp_sec_xxxxxxxxxxxx

Exemplo de cliente em Node (guarde as chaves em variáveis de ambiente):

const KLAUSPAY_API = "https://api.klauspay.com";

async function klausFetch(path, { method = "GET", body, idempotencyKey } = {}) {
  const headers = {
    "Content-Type": "application/json",
    "X-API-Key": process.env.KLAUSPAY_API_KEY,
    "X-API-Secret": process.env.KLAUSPAY_API_SECRET,
  };
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  const res = await fetch(KLAUSPAY_API + path, {
    method, headers, body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

Criar checkout / sessão

Crie o checkout no servidor. O valor vai em centavos, a moeda em ISO 4217. Informe o gateway a usar (ou deixe o padrão da conta) e os dados do comprador. Guarde o checkout_id no seu pedido antes de exibir o pagamento.

POST https://api.klauspay.com/v1/checkouts
Content-Type: application/json
X-API-Key: kp_pub_xxxx
X-API-Secret: kp_sec_xxxx
Idempotency-Key: pedido-12345

{
  "amount_cents": 9700,
  "currency": "USD",
  "description": "Método Completo",
  "gateway": "stripe",
  "success_url": "https://loja.com/obrigado",
  "customer": {
    "name": "Cliente",
    "email": "[email protected]",
    "document": "12345678901"
  }
}

Resposta (201):

{
  "checkout_id": "chk_a1b2c3",
  "status": "pending",
  "amount_cents": 9700,
  "currency": "USD",
  "checkout_url": "https://pay.klauspay.com/c/chk_a1b2c3"
}

Campos suportados (resumo):

[Nomes exatos de endpoint/campos: confirmar contra a API real do getfy antes de publicar como oficiais.]

Webhooks

Cadastre uma URL de webhook no painel. A KlausPay envia um POST assinado a cada evento. Valide a assinatura (HMAC) antes de processar e responda 200 rapidamente; processe de forma idempotente.

// POST /webhooks/klauspay  (seu backend)
import crypto from "crypto";

function verify(rawBody, signature) {
  const expected = crypto
    .createHmac("sha256", process.env.KLAUSPAY_WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post("/webhooks/klauspay", (req, res) => {
  if (!verify(req.rawBody, req.headers["x-klauspay-signature"]))
    return res.status(401).end();

  const { event, data } = req.body;
  if (event === "checkout.paid") {
    liberarAcesso(data.checkout_id); // idempotente
  }
  res.status(200).end();
});

Liberar acesso ao produto

Ao receber checkout.paid, localize o pedido interno pelo checkout_id e execute a liberação (envio de e-mail, criação de login na área de membros, ativação de assinatura). A operação deve ser idempotente: receber o mesmo evento duas vezes não pode duplicar acesso nem e-mails.

Erros comuns

Prompt pronto para colar no ChatGPT / Claude

Você vai integrar o checkout KlausPay (non-custodial). Siga EXATAMENTE a
documentação anexada. NÃO invente rotas nem campos.

Meu projeto:
- Stack: [ex.: Node + Express / PHP Laravel / Next.js]
- Gateway conectado: [Stripe / Asaas / Woovi]
- Objetivo: criar checkout, receber webhook checkout.paid e liberar acesso

Implemente, no servidor:
1. Cliente HTTP autenticado com X-API-Key + X-API-Secret (env vars).
2. Criação de checkout com amount_cents, currency e Idempotency-Key.
3. Materialização do pedido interno "pending" com gateway_ref = checkout_id
   ANTES do pagamento.
4. Endpoint de webhook com verificação HMAC e liberação idempotente.
5. Job de reconciliação como fallback do webhook.

Segredos apenas no backend. Valores em centavos.

Checklist antes de ir para produção

• API Key/Secret em variáveis de ambiente, nunca no frontend.
• Idempotency-Key em toda criação de checkout.
• Pedido interno pending criado antes do pagamento, com checkout_id.
• Webhook cadastrado, com validação HMAC sobre o corpo bruto.
• Liberação de acesso idempotente + job de reconciliação.
• Gateway conectado e testado em modo de teste antes do go-live.