API de cobrança

Autenticação

Crie a chave em Cobrar → API e webhook (a conta tem de ter a autenticação de dois fatores ativa). Envie-a no cabeçalho Authorization e guarde-a apenas no servidor. Escolha o acesso: “ler e criar cobranças” (loja) ou “só leitura” (reconciliação, relatórios). Uma chave só de leitura que tente criar recebe 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Criar cobrança

token: USDC ou SOL. valor: decimal com ponto, ou omita-o para um montante livre. validade_horas: 1, 24, 72, 168 ou 720 (por omissão, 24). externo_id: o número da encomenda na sua loja, único por conta. Envie Idempotency-Key (UUID) para poder repetir o pedido em segurança se a ligação falhar.

curl -X POST https://interban.online/api/v1/cobrancas \
  -H "Authorization: Bearer ib_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-4b1d-4c55-9a3e-0d2b7f9e1c11" \
  -d '{"token":"USDC","valor":"25.90","descricao":"Pedido 1042","externo_id":"1042","validade_horas":24}'

{
  "id": "9b2f…", "estado": "pendente", "externo_id": "1042",
  "token": "USDC", "decimais": 6, "valor_unidades": "25900000", "valor": "25.9",
  "url_pagamento": "https://interban.online/pagar/9b2f…",
  "solana_pay": "solana:<carteira>?amount=25.9&spl-token=EPjF…&reference=…",
  "expira_em": "…", "pagamento": null
}

Consultar

Os valores são sempre devolvidos como texto, em unidades inteiras do token (valor_unidades), sem perda de precisão. estado: pendente, paga, expirada ou cancelada. A lista é paginada: use limite (1 a 100, por omissão 50) e passe em depois o valor de proximo para ler a página seguinte; proximo nulo = fim. Para carteiras que preparam a transação no servidor (Solana Pay "transaction request"), use solana_pay_transacao; numa cobrança de montante livre, acrescente ?quantidade= ao URL antes de o codificar.

curl https://interban.online/api/v1/cobrancas/9b2f… -H "Authorization: Bearer ib_…"
curl "https://interban.online/api/v1/cobrancas?externo_id=1042" -H "Authorization: Bearer ib_…"
curl "https://interban.online/api/v1/cobrancas?limite=50&depois=<proximo>" -H "Authorization: Bearer ib_…"

Webhook: cobrança paga

Recebe um POST JSON com tipo cobranca.paga. Verifique a assinatura: HMAC-SHA256 em hex de "timestamp.corpo" com o seu segredo, e rejeite-o se o timestamp tiver mais de 5 minutos. Responda com 2xx; caso contrário, repetimos com intervalos crescentes. Use evento_id para ignorar repetições.

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

// body = the RAW request text (before JSON.parse)
// x-interbank-assinatura-anterior is only sent while the platform rotates keys: accept either one
export function webhookValido(corpo, cab, segredo) {
  const ts = cab['x-interbank-timestamp'];
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${ts}.${corpo}`).digest();
  return ['x-interbank-assinatura', 'x-interbank-assinatura-anterior'].some((h) => {
    const veio = Buffer.from(cab[h] ?? '', 'hex');
    return veio.length === esperado.length && timingSafeEqual(veio, esperado);
  });
}

Botão de pagamento no seu site (SDK)

Uma linha de script apresenta o botão com a sua marca e abre o checkout num novo separador; quando o pagamento é confirmado, o seu site recebe o evento checkout:paga. O evento serve apenas para a interface: entregue a encomenda só depois de confirmar no servidor (webhook assinado ou GET da cobrança).

<!-- data-cobranca: id returned by POST /api/v1/cobrancas · data-voltar: optional, must be on your own site -->
<script src="https://interban.online/sdk/v1/checkout.js" data-cobranca="9b2f…" data-voltar="/obrigado" async></script>
<script>
  addEventListener('checkout:paga', (e) => mostrarObrigado(e.detail.cobranca));
</script>

Receber em USDC a partir de qualquer token

Envie "aceita_conversao": true ao criar uma cobrança em USDC com montante definido. Na página de pagamento, quem paga escolhe SOL, USDT, JUP ou BONK, vê quanto vai gastar, e a mesma transação faz a conversão e entrega o montante exato em USDC na sua carteira. O webhook e a consulta são os mesmos: conta o USDC que chegou. Não está disponível no modo de teste.

curl -X POST https://interban.online/api/v1/cobrancas -H "Authorization: Bearer ib_…" -H "Content-Type: application/json" \
  -d '{"token":"USDC","valor":"49.90","externo_id":"1043","aceita_conversao":true}'
# → { "aceita_conversao": true, "url_pagamento": "https://interban.online/pagar/…", … }
# the payer picks SOL, USDT, JUP or BONK on the page; the merchant receives exactly 49.90 USDC

Ambiente de testes (sandbox)

Crie uma chave no modo Teste (começa por ib_test_). Usa a mesma API, mas só vê e cria cobranças de teste, que ficam na rede de testes (modo: "teste" na resposta e no webhook) e nunca entram na sua tesouraria. Para testar sem carteira, simule o pagamento: POST /api/v1/cobrancas/{id}/simular-pagamento (com montante livre, envie {"valor": "…"}). O webhook cobranca.paga chega assinado, tal como o real. A chave de produção não simula pagamentos, e cada chave não vê as cobranças da outra.

# test key (ib_test_…): same API, test charges only, test network
curl -X POST https://interban.online/api/v1/cobrancas -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" -d '{"token":"USDC","valor":"25.90","externo_id":"teste-1"}'
# → { "id": "9b2f…", "modo": "teste", "rede": "devnet", "estado": "pendente", … }

curl -X POST https://interban.online/api/v1/cobrancas/9b2f…/simular-pagamento -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…"
# → { "estado": "paga", "pagamento": { "assinatura": "simulado_…", … } } plus the cobranca.paga webhook with "modo": "teste"

Erros e limites

Os erros são devolvidos como { erro: { codigo, mensagem } }. 401 chave inválida ou revogada · 403 a chave não tem o âmbito da operação · 404 cobrança de outra conta ou inexistente · 409 externo_id repetido ou Idempotency-Key reutilizada com outro corpo · 422 dados inválidos · 429 mais de 120 pedidos por minuto por chave.

Contrato (OpenAPI)

A especificação OpenAPI 3.1 completa (cobranças, erros e webhook) está em /api/v1/openapi.json. Pode importá-la no Postman, no Insomnia ou num gerador de clientes. É gerada a partir dos mesmos esquemas que os testes verificam contra as respostas reais.

curl https://interban.online/api/v1/openapi.json