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 ocurl -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çalho | Valor |
|---|---|
X-Kirvex-Timestamp | Hora atual em segundos Unix, por exemplo 1767225600 |
X-Kirvex-Signature | t=<o mesmo timestamp>,v1=<assinatura em hex> |
Para calcular a assinatura:
- 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).
- 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. - 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.