Autenticação

A InfraIO Pay tem duas superfícies de API com modelos de autenticação diferentes. Escolha a que combina com quem está chamando:

Esta página cobre a superfície B2B, a que você chama do seu servidor com um par de chaves de API. A superfície do dashboard é usada pelo dashboard do lojista da InfraIO Pay e não é uma superfície pública de integração.

Envie sempre o path completo, incluindo o prefixo /b2b, e assine esse mesmo path (veja abaixo).

Endpoints

Mesmo padrão de URL — o ambiente é controlado pelo prefixo da chave (pk_test_… vs pk_live_…), não pela URL.

Par de chaves

Você pega dois valores no dashboard do lojista (Developers → API keys → + Add key):

• Chave publicável (pk_test_… ou pk_live_…) — identifica a sua conta. Enviada como X-Client-ID. Seguro embutir no seu bundle do navegador (o SDK já faz isso).
• Chave secreta (sk_test_… ou sk_live_…) — a chave de assinatura HMAC. Só servidor. Trate como uma senha de banco de dados.

Assinando uma requisição

Toda chamada para /b2b/v1/* leva três headers:

X-Client-ID:  pk_live_70d0becbd7a53047b0dfe88a960d10ad
X-Timestamp:  1715990400
X-Signature:  9a8b7c6d…             (hex HMAC-SHA256)

A assinatura é calculada sobre uma string canônica:

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

• METHOD — verbo HTTP em maiúsculas (POST, GET, …).
• PATH — path da requisição incluindo o prefixo /b2b, sem o host e sem a query string (por exemplo, /b2b/v1/checkout-sessions/quick). O prefixo precisa estar presente. Parâmetros de query não são assinados — para um GET …?cursor=…&limit=20, assine só o path, não a parte ?….
• TIMESTAMP — unix segundos, como string decimal (por exemplo, "1715990400"), batendo exatamente com o X-Timestamp.
• BODY — bytes brutos do body da requisição. String vazia para GET/DELETE.

Assine com HMAC-SHA256 chaveado pela chave secreta, saída hex:

import { createHmac } from "node:crypto";
 
function sign({ method, path, body, secret }: {
  method: string; path: string; body: string; secret: string;
}) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const input = [method.toUpperCase(), path, timestamp, body].join("\n");
  const signature = createHmac("sha256", secret).update(input).digest("hex");
  return { timestamp, signature };
}

package infraio
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)
 
func Sign(method, path, body, secret string) (timestamp, signature string) {
    timestamp = strconv.FormatInt(time.Now().Unix(), 10)
    input := method + "\n" + path + "\n" + timestamp + "\n" + body
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(input))
    return timestamp, hex.EncodeToString(mac.Sum(nil))
}

import hmac, hashlib, time
 
def sign(method: str, path: str, body: str, secret: str):
    timestamp = str(int(time.time()))
    input_ = f"{method}\n{path}\n{timestamp}\n{body}"
    signature = hmac.new(
        secret.encode(), input_.encode(), hashlib.sha256
    ).hexdigest()
    return timestamp, signature

Por que HMAC, e não Bearer?

Uma API de token Bearer puro envia o seu único segredo pela rede em toda requisição. Quem capturar um log de proxy com terminação TLS ganha as chaves da sua conta. Assinar com HMAC significa que o segredo nunca viaja — só a assinatura derivada dele, que é de uso único (vinculada àquela requisição exata + aquele minuto exato).

O trade-off: você calcula uma assinatura a cada chamada. Ainda não há um SDK de servidor, mas o helper acima tem cerca de 15 linhas por linguagem.

Tolerância do timestamp

A tolerância é de ±5 minutos (300 segundos). Uma requisição fora dessa janela é rejeitada com 401 invalid_signature. Duas implicações:

1. Sincronize o relógio do seu servidor via NTP. Um cron de longa duração com relógio desviado vai falhar intermitentemente.
2. Não pré-compute e enfileire assinaturas. Se uma requisição fica numa fila de retry por mais de 5 min, a assinatura expira.

Escopos de chave

Chaves secretas carregam um ou mais destes bundles de escopo:

O dashboard emite uma chave “full access” por padrão (os quatro escopos). Você pode criar uma chave com escopo restrito em Developers → API keys → + Add key e marcar só os escopos que a integração precisa.

Falha na verificação

Se a assinatura, o X-Client-ID ou o timestamp forem inválidos, a requisição é rejeitada com 401 INVALID_SIGNATURE antes de chegar à API. Somente as requisições /b2b/v1/* são assinadas dessa forma. Os webhooks usam um esquema separado (veja abaixo).

Próximos passos

• Erros — formato da resposta em 4xx/5xx.
• Segurança → Chaves de API — rotação, revogação, o que fazer se um segredo vaza.
• Webhooks → Verificação de assinatura — usa um esquema HMAC diferente (header X-Signature: sha256=…, assina X-Timestamp + "." + raw_body, mais um X-Signature-Prev opcional durante a janela de tolerância de 24 horas da rotação). Não misture os esquemas — eles compartilham o algoritmo de hash mas os bytes assinados e a família de segredos (whsec_… vs sk_…) são diferentes.