Glossário

Referência rápida dos termos, siglas e conceitos usados na API.

Termos da API

access_token Token JWT retornado pelo endpoint OAuth (POST /v2/oauth/token). Válido por 1 hora. Deve ser enviado em todas as requisições autenticadas no header Authorization: Bearer {token}.

client_id / client_secret Credenciais da sua integração. Obtidas no painel da BSPAY. Usadas para gerar o access_token via OAuth.

external_id Identificador da transação no seu sistema. Máximo 64 caracteres. Permite rastrear a transação de ponta a ponta sem depender do transaction_id gerado pela BSPAY. Único por conta.

transaction_id Identificador único da transação gerado pela BSPAY. Formato: string hexadecimal de 32 caracteres (ex: 49c498a9c5ec5e7d3202d5a1252c85b6). Use para consultar status e correlacionar webhooks.

postback_url URL HTTPS do seu servidor que receberá os webhooks. Deve responder HTTP 200 em até 10 segundos.

amount_net Valor líquido creditado após descontar a taxa (fee). É o que efetivamente entra no saldo.

amount Valor bruto da transação, antes de qualquer taxa.

fee Taxa cobrada pela BSPAY sobre a transação. amount_net = amount - fee.

source Origem do cash-in PIX. dynamic_qr = cobrança criada via API. static = carteira fixa (QR estático ou endereço crypto permanente).

Termos PIX

Chave PIX Identificador vinculado a uma conta bancária. Pode ser: CPF/CNPJ, e-mail, telefone celular ou chave aleatória (EVP).

QR Code Dinâmico Cobrança PIX criada via API com valor e validade definidos. Gerada pelo endpoint POST /v2/transactions/cashin. Cada QR é único e de uso único.

QR Code Estático (Carteira Fixa) QR permanente vinculado à sua conta. Aceita qualquer valor ou um valor fixo predefinido. Identificado por qrcode_id.

EMV / Brcode Padrão de dados do QR Code PIX. String que começa com 00020126.... É o conteúdo que o app bancário lê para processar o pagamento.

E2E ID (End-to-End ID) Identificador único do pagamento gerado pelo Banco Central. Formato: E{ispb}{data}{hora}{sequencial}. Exemplo: E9035200620260404150000ABCD1234. Disponível no payload do webhook após confirmação.

DICT Diretório de Identificadores de Contas Transacionais — o sistema do Banco Central que armazena as chaves PIX e as vincula a contas bancárias.

ISPB Identificador do Sistema de Pagamentos Brasileiro. Código de 8 dígitos que identifica cada instituição financeira no sistema PIX.

Payer / Pagador Quem envia o PIX. Disponível nos campos payer_name e payer_document do webhook após confirmação.

Receiver / Recebedor Quem recebe o PIX. No contexto da BSPAY, é a conta do seu cliente na plataforma.

Infração / Devolução Mecanismo do Banco Central que permite solicitar a devolução de um PIX (estorno). Gera eventos refund_confirmed ou refund_responded nos webhooks.

Txid Identificador único do QR Code no sistema do recebedor. Diferente do transaction_id da BSPAY — é o ID usado na validação do brcode.

Termos de Pagamento

Cash-in Recebimento de valores na conta. Pode ser via PIX (QR dinâmico ou estático) ou depósito de criptomoedas.

Cash-out Envio de valores da conta. PIX para chave de destino ou saque cripto para endereço externo.

Split de Pagamento Divisão automática do valor de uma transação entre múltiplas contas BSPAY no momento da liquidação. Configurado pelo campo split[] no payload do cashin. Suporta percentual (percentage) ou valor fixo (type: "fixed" + amount). Soma dos percentuais não pode ultrapassar 95%.

Carteira Fixa Endereço permanente para receber criptomoedas. Diferente do cash-in temporário (expira em 30 min), aceita depósitos a qualquer momento sem criação prévia. Gera evento cashin.confirmed com source: static.

Transferência Interna Movimentação de saldo entre contas BSPAY. Campo obrigatório: username da conta de destino. Rota: POST /v2/internal_transfers/payment.

Conversão Troca de saldo entre moedas dentro da conta (ex: BRL → USDT). Retorna rate (cotação), from_amount, to_amount e fee. Rota: POST /v2/conversions/new.

rate Taxa de câmbio aplicada em uma conversão. Exemplo: 5.0916 significa 1 USDT = R$ 5,0916.

chain Rede blockchain usada no depósito ou saque cripto. Exemplos: tron, ethereum, bsc, polygon, solana, bitcoin.

tx_hash Hash da transação on-chain. Identificador único da movimentação na blockchain. Disponível no webhook após confirmação.

deposit_address Endereço na blockchain onde o pagador deve enviar os fundos. Gerado para cada depósito cripto.

balance / balance_lockedbalance = saldo disponível para uso. balance_locked = saldo bloqueado por operações em andamento ou compliance.

page / page_size / has_next / has_prev Campos de paginação usados na listagem de transações. page_size máximo: 100. has_next e has_prev indicam se existem mais páginas.

request_id Identificador único gerado pela BSPAY para cada requisição. Útil para suporte e debug — inclua nos chamados de erro.

Rate Limiting Controle de frequência de requisições por IP e por credencial. Ao exceder, a API retorna HTTP 429 com o código RATE_LIMIT_EXCEEDED. Limites variam por endpoint (30–1000 req/min).

Termos de Segurança

Bearer Token Forma de autenticação via header HTTP: Authorization: Bearer {access_token}. Todas as rotas da BSPAY exigem este header.

OAuth 2.0 Client Credentials Fluxo de autenticação M2M (machine-to-machine) usado pela BSPAY. Não envolve usuário final — apenas client_id e client_secret.

HMAC-SHA256 Algoritmo de assinatura usado para validar a autenticidade dos webhooks internos entre o controller e a BSPAY.

Idempotência Propriedade que garante que processar o mesmo evento múltiplas vezes não cause efeitos duplicados. Use transaction_id como chave de idempotência no seu sistema.

Status de Transação

Moedas Suportadas

Eventos de webhook estão na página dedicada Webhooks com payloads completos e validação HMAC.