Carteira Fixa

Carteiras fixas são endereços/chaves permanentes para receber depósitos. Diferente do cashin temporário (expira em ~30 min), a carteira fixa aceita pagamentos a qualquer momento — ideal para doações, recorrências e depósitos contínuos.

Requer autenticação

POST/v2/transactions/wallet

Provisiona uma carteira/chave permanente atrelada à sua conta. Qualquer depósito recebido nela dispara o webhook wallet_deposit.

Parâmetros

currencystringobrigatório

Moeda da carteira: BRL, MXN, USDT, USDC, BTC, ETH, SOL, BNB.

chainstring

Rede blockchain (obrigatório para cripto): tron, ethereum, bsc, polygon, solana, bitcoin. Omitir para BRL/MXN.

Rate limit

30 reqs/min por credencial.

Erros

Código	HTTP	Descrição
`INVALID_CURRENCY`	422	Moeda não suportada
`UNSUPPORTED_CHAIN`	422	Chain não suportada para a moeda
`UNSUPPORTED_CURRENCY`	422	Moeda não disponível para wallet fixa
`WALLET_LIMIT_REACHED`	409	Limite de carteiras fixas atingido para a credencial
`PROVIDER_ERROR`	502	Falha ao provisionar com provedor — retryable

Cripto (USDT/USDC/BTC/ETH/SOL)

cURL

PHP

JavaScript

Python

curl -X POST https://api.bspay.co/v2/transactions/wallet \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "chain": "tron"
  }'

PIX (BRL) — só currency:

curl -X POST https://api.bspay.co/v2/transactions/wallet \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "BRL" }'

SPEI (MXN) — só currency:

curl -X POST https://api.bspay.co/v2/transactions/wallet \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "MXN" }'

200 Cripto

200 PIX

200 SPEI

422 Chain

{
  "success": true,
  "data": {
    "wallet_id": 41,
    "address": "TWMrdKSXaTbpcjBAT5PEzL4LtkC9fL4HQk",
    "currency": "USDT",
    "chain": "tron",
    "min_confirmations": 20,
    "created_at": "2026-04-30T13:00:00Z"
  },
  "request_id": "c1bb28cd2cc482db4db5ae88",
  "timestamp": "2026-04-30T13:00:00Z"
}

Redes suportadas

Moeda	Chains	Confirmações típicas
USDT	tron (TRC20), ethereum (ERC20), bsc (BEP20), polygon	20 / 12 / 15 / 100
USDC	ethereum, bsc, polygon, arbitrum, base, optimism	20 / 12 / 15 / 100 / 32
BTC	bitcoin	6
ETH	ethereum	12
SOL	solana	32
BNB	bsc	15
BRL	— (PIX nativo)	instantâneo
MXN	— (SPEI nativo)	~30s

Webhook de depósito

Toda vez que a wallet receber um depósito, você recebe wallet_deposit:

{
  "event": "wallet_deposit",
  "transaction_id": "wdep_abc123",
  "wallet_id": 41,
  "address": "TWMrdKSXaTbpcjBAT5PEzL4LtkC9fL4HQk",
  "chain": "tron",
  "currency": "USDT",
  "amount_gross": "5.403",
  "amount_net": "4.403",
  "fee": "1.000",
  "tx_hash": "24669f333...",
  "confirmed_at": "2026-04-30T13:00:00Z"
}

amount_net é o valor efetivamente creditado no seu saldo (após fee BSPAY). Veja todos os detalhes em Webhooks → Eventos.

Cashin temporário vs Carteira fixa

	Cashin temporário	Carteira fixa
Endpoint	`POST /v2/transactions/cashin`	`POST /v2/transactions/wallet`
Validade	~30 min	Permanente
Reuso	Não — gera novo `transaction_id`	Sim — mesmo endereço sempre
Identifica pagador?	Via `payer.name`/`document`	Não (qualquer um pode depositar)
Webhook	`cashin.confirmed`	`wallet_deposit`
Caso de uso	Pedido único, checkout	Doação, recorrência, on-ramp

AnteriorConversãoPróximoListar Transações