DOCS

Autenticação

Chave de API, Idempotency-Key e a assinatura opcional dos pedidos.

Todo pedido vai para https://api.kirvex.com.br com a sua chave secreta. A chave decide o modo: sk_test_ vai para o sandbox do adquirente e nunca cobra de verdade; sk_live_ movimenta dinheiro real.

Chave de API

Envie a chave no cabeçalho Authorization, de uma destas formas:

  • Authorization: Bearer sk_live_...
  • Authorization: Basic <base64("sk_live_...:")> — a chave como usuário e a senha vazia (é o que o curl -u "$KIRVEX_SECRET_KEY:" faz).

A chave é secreta: use-a só no seu servidor, nunca no navegador ou no app.

Idempotency-Key

Todo pedido que cria ou altera algo (POST, PUT, PATCH, DELETE) exige o cabeçalho Idempotency-Key, com um valor único por intenção — por exemplo pedido-1234-pix-1. Até 255 caracteres, só letras, números e _ - : ..

  • Repetir o pedido com a mesma chave e o mesmo corpo devolve a mesma resposta, com o cabeçalho idempotent-replayed: true. Nada é cobrado duas vezes.
  • A mesma chave com outro corpo é recusada com 409 idempotency_conflict.

Assinatura dos pedidos (opcional)

Você pode assinar cada pedido que escreve, para provar que ele saiu do seu servidor e não foi alterado no caminho. Hoje a assinatura é opcional: um pedido sem os dois cabeçalhos abaixo é aceito só com a chave. Mas, se você mandar qualquer um deles, os dois passam a ser exigidos e a assinatura precisa estar certa, senão o pedido volta 401 unauthorized.

CabeçalhoValor
X-Kirvex-TimestampHora atual em segundos Unix, por exemplo 1767225600
X-Kirvex-Signaturet=<o mesmo timestamp>,v1=<assinatura em hex>

Para calcular a assinatura:

  1. Calcule o SHA-256, em hex minúsculo, do corpo exatamente como será enviado (os mesmos bytes; corpo vazio = SHA-256 de uma string vazia).
  2. Monte o texto a assinar, separando com quebra de linha (\n): MÉTODO, o caminho sem domínio e sem query string (por exemplo /v1/charges), o hash do passo 1 e o timestamp.
  3. Calcule o HMAC-SHA256 desse texto com a sua chave secreta (sk_... inteira) e escreva em hex minúsculo.

O timestamp pode estar no máximo 5 minutos adiantado ou atrasado em relação à hora do servidor da Kirvex. Mantenha o relógio do seu servidor sincronizado.

import { createHash, createHmac } from 'node:crypto';

const KEY = process.env.KIRVEX_SECRET_KEY!; // sk_live_... ou sk_test_...

export async function kirvexPost(path: string, body: unknown, idempotencyKey: string) {
  const raw = JSON.stringify(body);
  const t = Math.floor(Date.now() / 1000).toString();
  const bodyHash = createHash('sha256').update(raw).digest('hex');
  const v1 = createHmac('sha256', KEY)
    .update(`POST\n${path}\n${bodyHash}\n${t}`)
    .digest('hex');

  const res = await fetch(`https://api.kirvex.com.br${path}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
      'X-Kirvex-Timestamp': t,
      'X-Kirvex-Signature': `t=${t},v1=${v1}`,
    },
    body: raw, // os mesmos bytes que foram assinados
  });
  return res.json();
}

Atenção: assine o corpo que vai de fato no pedido. Gerar o JSON duas vezes (uma para assinar, outra para enviar) pode mudar espaços ou a ordem dos campos, e a assinatura deixa de bater.

Avisos que a Kirvex envia

Os webhooks que a Kirvex manda para o seu sistema têm uma assinatura própria, feita com o secret do endpoint. Veja como conferir em Webhooks.

On this page