Visão Geral

Como funciona

Toda operação financeira na BSPAY segue o mesmo padrão: autentique, execute, receba a confirmação. Não importa se é PIX, cripto ou SPEI — a interface é a mesma.

Cash-in — Receber

Autentique

POST /v2/oauth/token com suas credenciais. Token válido por 1 hora.

Crie a cobrança

POST /v2/transactions/cashin com currency e amount. BRL retorna QR Code PIX. Cripto retorna endereço de depósito. MXN retorna CLABE.

Receba o webhook

O cliente paga → BSPAY confirma → postback_url recebe o evento cashin.confirmed com saldo atualizado.

Cash-out — Enviar

Valide o destino

PIX: qualquer chave válida (CPF, CNPJ, e-mail, telefone, aleatória). Cripto: endereço on-chain na rede correta.

Execute o saque (com HMAC)

POST /v2/transactions/cashout com currency, amount, key e network (para cripto). Esta rota exige assinatura HMAC nos headers X-Signature + X-Timestamp + X-Nonce — ver Autenticação → HMAC.

Confirme a liquidação

Resposta inicial é 202 Accepted com status: pending. A confirmação chega via webhook cashout.confirmed (sucesso) ou cashout.error (falha — saldo refundado automaticamente).

Cashout, transferência interna e conversão FX exigem HMAC. Cashin, balance e listagens usam apenas Bearer token.

Ciclo de vida da transação

pending

Cobrança/saque criado. Aguardando processamento.

confirmed

Pagamento liquidado. Saldo creditado/debitado.

failed

Operação falhou. Saldo refundado se aplicável.

Moedas suportadas

MoedaMétodo / ChainsOperações
BRLPIXCash-in, Cash-out, Wallet fixa, Conversão
MXNSPEICash-in, Cash-out, Wallet fixa
USDTTron, Ethereum, BSC, Polygon, ArbitrumCash-in, Cash-out, Wallet fixa, Conversão
USDCEthereum, BSC, Polygon, Arbitrum, Base, OptimismCash-in, Cash-out, Wallet fixa, Conversão
BTCBitcoinCash-in, Cash-out, Wallet fixa, Conversão
ETHEthereum, Arbitrum, Base, OptimismCash-in, Cash-out, Wallet fixa, Conversão
SOLSolanaCash-in, Cash-out, Wallet fixa, Conversão
BNBBSCCash-in, Cash-out, Wallet fixa, Conversão

Padrão de resposta

Todos os endpoints retornam o mesmo formato:

{
  "success": true,
  "data": { ... },
  "request_id": "7ff30940df6de2e368af7ea2",
  "timestamp": "2026-04-04T13:20:53Z"
}

Em caso de erro:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo insuficiente para esta operação.",
    "group": "BUSINESS",
    "retryable": false
  }
}

Detalhes sobre códigos de erro em Respostas HTTP.

AnteriorGlossárioPróximoCash-in

Esta página foi útil?