Cash-in

Requer autenticação

POST/v2/transactions/cashin

Cria uma cobrança e retorna os dados de pagamento. PIX retorna QR Code, cripto retorna endereço de depósito temporário, SPEI retorna CLABE.

O valor é creditado no seu saldo assim que confirmado. Você recebe o webhook cashin.confirmed na postback_url (ver Webhooks).

Endereço cripto temporário expira em ~30min. Para endereço permanente, use Carteira Fixa.

Parâmetros

amountnumberobrigatório

Valor da cobrança (até 2 decimais). Mínimo: 1.00 BRL · 2.00 USDT/USDC · 0.0001 BTC · 0.001 ETH/SOL.

currencystringobrigatório

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

chainstring

Blockchain de origem do depósito (obrigatório para cripto): tron, ethereum, bsc, polygon, solana, bitcoin. Omitir para BRL/MXN.

chain ≠ network: chain é a blockchain (livro-razão); network (usada em cashout) é a rede de transmissão, que pode ser a mainnet ou um L2 (ex: chain: ethereum + network: arbitrum). Para Tron/BTC/Solana/BSC ambos coincidem.

external_idstring

Identificador único no seu sistema (idempotência). Reenviar o mesmo external_id retorna a mesma transação. Máx 150 caracteres.

postback_urlstring

URL HTTPS que receberá o webhook cashin.confirmed. Sobrescreve o webhook default da credencial.

payer.namestring

Nome do pagador. Recomendado para BRL.

payer.documentstring

CPF ou CNPJ do pagador. Recomendado para BRL.

payer.emailstring

E-mail do pagador. Opcional.

splitarray

Divisão automática do valor entre contas BSPAY. Ver Split.

Rate limit

12000 reqs/min por credencial.

Erros

Código	HTTP	Descrição
`MISSING_REQUIRED_FIELD`	400	Campo obrigatório ausente (`amount`, `currency`)
`INVALID_AMOUNT`	422	Valor inválido ou abaixo do mínimo
`INVALID_CURRENCY`	422	Moeda não suportada
`UNSUPPORTED_CHAIN`	422	Chain não suportada para a moeda — `details.supported` lista chains válidas
`BELOW_MIN_LIMIT`	409	Valor abaixo do mínimo da moeda
`EXCEEDS_MAX_LIMIT`	409	Valor acima do máximo permitido — `details.max_amount`
`LIMIT_EXCEEDED`	409	Limite diário atingido
`DUPLICATE_EXTERNAL_ID`	409	`external_id` já usado em outra transação
`PROVIDER_ERROR`	502	Erro no provedor PIX/blockchain — retryable

PIX (BRL)

cURL

PHP

JavaScript

Python

curl -X POST https://api.bspay.co/v2/transactions/cashin \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "external_id": "order_001",
    "payer": {
      "name": "João Silva",
      "document": "11370243480"
    },
    "postback_url": "https://seusite.com/webhook"
  }'

Cripto — adicionar chain ao body:

curl -X POST https://api.bspay.co/v2/transactions/cashin \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDT",
    "chain": "tron",
    "external_id": "crypto_001",
    "postback_url": "https://seusite.com/webhook"
  }'

200 PIX

200 USDT

422 Chain

409 Duplicate

{
  "success": true,
  "data": {
    "transaction_id": "bc29f8989cc0ab75a9c4a691e716bbf4",
    "external_id": "order_001",
    "currency": "BRL",
    "amount": 100.00,
    "fee": 0.30,
    "payment_method": "pix",
    "payment_info": {
      "qrcode": "00020101021226640014br.gov.bcb.pix...",
      "expiration": 3600,
      "expires_at": "2026-04-04T11:20:53-03:00"
    },
    "status": "pending",
    "postback_url": "https://seusite.com/webhook",
    "created_at": "2026-04-04T10:20:53-03:00"
  },
  "request_id": "7ff30940df6de2e368af7ea2",
  "timestamp": "2026-04-04T13:20:53Z"
}

AnteriorVisão GeralPróximoCash-out