API e webhooks

Começar

Introdução

A API do vendedor cria um pedido de checkout. Os webhooks avisam o seu sistema quando uma venda é aprovada. Não há outro recurso público de cobrança, cliente ou extrato nesta versão.

Começar

Primeiros passos

Gere uma chave em API Keys, no painel. Chame a API só a partir do seu servidor. Cadastre uma URL HTTPS em Webhooks para receber o evento de venda aprovada.

Começar

Autenticação e proteção da chave

Envie Authorization: Bearer e a chave secreta. A chave identifica a conta, então não vai para página, aplicativo de celular nem repositório. Pedido sem chave, ou com chave inválida, responde 401. A verificação de identidade precisa estar aprovada; sem isso a resposta é 403.

Authorization: Bearer kp_live_sua_chave

Começar

Ambientes

Não há uma URL de sandbox separada para a chave do vendedor. O mesmo endpoint cria o pedido. O webhook traz livemode: true só quando o evento é de dinheiro real. O botão Enviar teste manda livemode: false e test_mode: true.

Pedidos

POSTCriar pedido

Cria um pedido já ligado à conta da chave e devolve o link do checkout. O valor vai em centavos.

• 201 Pedido criado. Corpo com id, status e checkoutUrl.
• 400 JSON inválido, nome, valor ou e-mail fora do formato.
• 401 Chave ausente ou inválida.
• 403 Verificação pendente ou conta em restrição.
• 429 Muitas tentativas de autenticação ou muitos pedidos.
• 503 Plataforma em manutenção.
• 500 Falha interna.

POST /api/v1/checkout-orders
Authorization: Bearer kp_live_sua_chave
Content-Type: application/json

{"productName":"Curso","amountMinor":9700,"buyerEmail":"aluno@exemplo.com"}

{
  "id": "uuid-do-pedido",
  "status": "created",
  "checkoutUrl": "https://www.kyverapay.com/checkout/uuid-do-pedido"
}

const response = await fetch("https://www.kyverapay.com/api/v1/checkout-orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KYVERAPAY_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ productName: "Curso", amountMinor: 9700 }),
});

$ch = curl_init("https://www.kyverapay.com/api/v1/checkout-orders");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer ".$key, "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["productName" => "Curso", "amountMinor" => 9700]),
]);

import os, requests
requests.post(
  "https://www.kyverapay.com/api/v1/checkout-orders",
  headers={"Authorization": f"Bearer {os.environ['KYVERAPAY_SECRET_KEY']}"},
  json={"productName": "Curso", "amountMinor": 9700},
)

Webhooks

Cadastrar a URL

Em Webhooks, informe uma URL HTTPS pública. Endereço de rede interna é recusado. O segredo fica na conta para você validar a assinatura. Não existe cadastro de URL por esta API.

Webhooks

Validar autenticidade

O cabeçalho X-Kyverapay-Signature vem como t=<unix>,v1=<hex>. Calcule HMAC-SHA256 do texto timestamp.corpo com o segredo e compare com v1. X-Kyverapay-Event traz o nome do evento. X-Kyverapay-Livemode é true só em dinheiro real.

import { createHmac, timingSafeEqual } from "node:crypto";

function validSignature(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const left = Buffer.from(expected);
  const right = Buffer.from(parts.v1 ?? "");
  return left.length === right.length && timingSafeEqual(left, right);
}

Webhooks

Reenvio e idempotência

Se o seu servidor não responder 2xx, a entrega falha e volta a ser tentada em 1 minuto, 5 minutos, 30 minutos, 2 horas e 12 horas. Resposta 500, 408 ou 429 entra nessa fila. O cabeçalho X-Kyverapay-Delivery identifica a entrega: grave esse valor e ignore a repetição. Também dá para reenviar pela página de Webhooks.

Webhooks

Evento disponível

O evento que o código envia ao vendedor é transaction.approved. O teste do painel usa o mesmo nome, com livemode false, test_mode true e source webhook_test.

{
  "event": "transaction.approved",
  "livemode": false,
  "test_mode": true,
  "source": "webhook_test",
  "transaction": {
    "id": 999999,
    "description": "Venda de teste — PIX",
    "amount": 149.9,
    "method": "pix",
    "status": "approved",
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}