Primeiros Passos com a API

A API de pagamentos da Isp Banking permite gerar cobranças PIX (com QR Code dinâmico ou link de pagamento), consultar o status de uma transação, solicitar a conversão de DePix para PIX (saque) e receber notificações automáticas via webhook quando um pagamento é confirmado. Ela foi desenhada para ser consumida por qualquer linguagem de programação capaz de fazer requisições HTTP — não há SDK obrigatório nem dependência de biblioteca proprietária.

Este guia cobre o caminho conceitual até a primeira requisição bem-sucedida. Para o contrato exato de cada endpoint (parâmetros obrigatórios, formatos de resposta, exemplos completos), use sempre a referência Swagger como fonte de verdade — os nomes de campos e exemplos abaixo são ilustrativos.

Antes de integrar, é necessário ter uma conta na plataforma. Após o cadastro, a conta passa por uma revisão da equipe de compliance (política de low-KYC) antes de poder movimentar valores — esse processo pode levar alguns dias úteis.

Em seguida, configure a carteira Liquid Network (por exemplo, uma carteira não-custodial como o SideSwap) que receberá os valores em DePix/L-BTC gerados a partir dos pagamentos PIX processados pela sua integração. Cada conta pode ter uma ou mais carteiras associadas.

Com a conta aprovada, você encontra seu código de integração (o parâmetro code usado em todas as chamadas à API) na seção de configurações do seu painel. Esse código identifica sua conta e a carteira associada a ela — é ele que a API usa para saber para onde direcionar cada cobrança gerada, sem exigir um fluxo de OAuth ou emissão de token separado.

O fluxo mais simples é gerar um link/QR Code de cobrança PIX informando seu código de integração e o valor desejado (em centavos). Conceitualmente, uma chamada GET a esse endpoint se parece com:

A resposta traz, entre outros campos, um identificador da transação (id), o código PIX "copia e cola" (qrCopyPaste) e uma URL para a imagem do QR Code (qrImageUrl). Também é possível solicitar diretamente a imagem do QR Code (em vez de JSON) passando um parâmetro que ative esse modo — veja a referência Swagger para o nome exato e todas as variações suportadas.

Depois de criar a cobrança, existem duas formas de saber quando ela foi paga: consultar periodicamente um endpoint de status usando o identificador da transação (polling), ou configurar uma URL de callback (webhook) para ser notificado automaticamente assim que o pagamento for confirmado — a segunda opção é a recomendada para produção, pois reduz latência e carga desnecessária na API.

O funcionamento detalhado de webhooks — incluindo validação de assinatura, idempotência e um checklist antes de ir para produção — está descrito no artigo Webhooks e notificações em tempo real no blog.

A plataforma disponibiliza um ambiente de sandbox, com endpoints equivalentes prefixados por /sandbox, que permite simular diferentes status de pagamento sem gerar cobranças reais. A especificação Swagger do ambiente de testes está disponível separadamente em /sandbox/api-docs. Recomendamos validar toda a integração — geração de cobrança, consulta de status e recebimento de webhook — nesse ambiente antes de apontar para produção.

• Autenticação — como o código de integração e os webhooks são validados.
• Erros e Códigos de Status — como interpretar e tratar respostas de erro.
• FAQ Técnico — sandbox, rate limiting, versionamento e suporte.
• Referência Swagger completa — todos os endpoints, parâmetros e exemplos.