Cash-out

Requer autenticação
POST/v2/transactions/cashout

Envia um pagamento para uma chave PIX (BRL), endereço de carteira cripto ou CLABE (MXN/SPEI). O saldo é debitado imediatamente, mas a liquidação é assíncrona — a resposta inicial retorna 202 Accepted com status: pending e a confirmação chega via webhook.

Headers

Authorization: Bearer {access_token}
Content-Type:  application/json
X-Signature:   hex(hmac_sha256(timestamp + "." + nonce + "." + body, signing_key))
X-Timestamp:   <unix_seconds>
X-Nonce:       <uuid_v4>

Body

Parâmetros
external_idstringobrigatório
ID único no seu sistema (idempotência). Reenviar o mesmo external_id retorna a mesma transação.
amountnumberobrigatório
Valor a enviar (até 2 decimais, exceto cripto que aceita até 8).
currencystringobrigatório
Moeda: BRL, MXN, USDT, USDC, BTC, ETH, SOL, BNB.
keystringobrigatório
Destino. PIX: chave (CPF, CNPJ, e-mail, telefone, EVP/aleatória). Cripto: endereço da carteira. SPEI: CLABE 18 dígitos.
key_typestring
Para PIX: cpf, cnpj, email, phone, random. Para cripto/SPEI: omitir.
networkstring
Rede de transmissão usada para enviar a tx (cripto): tron, ethereum, bsc, polygon, solana, bitcoin. Obrigatório quando currency é cripto.

networkchain: network é a rede onde a tx é broadcast (pode ser uma L2 como arbitrum, base, optimism); chain é a blockchain de origem (livro-razão). Para Tron/BTC/Solana/BSC ambos coincidem; para ETH/USDC em L2, podem diferir.

namestring
Nome do recebedor. Recomendado para PIX, obrigatório para SPEI.
bank_codestring
Código do banco (SPEI). Auto-detectado via CLABE se omitido.
descriptionstring
Descrição do pagamento. Aparece no comprovante.
postback_urlstring
URL HTTPS para webhook. Sobrescreve default da credencial.

Rate limit

6000 reqs/min por credencial.

Resposta

202 Accepted — operação aceita, processamento assíncrono. Aguarde o webhook cashout.confirmed (sucesso) ou cashout.failed (falha — saldo refundado automaticamente).

Erros

CódigoHTTPDescrição
MISSING_REQUIRED_FIELD400Campo obrigatório ausente — details.field
MISSING_SIGNATURE / INVALID_SIGNATURE401Header HMAC ausente ou inválido
INVALID_TIMESTAMP401X-Timestamp fora da janela ±5 min
REPLAY_DETECTED401X-Nonce já usado nos últimos 5 min
INVALID_AMOUNT422Valor inválido
INVALID_CURRENCY422Moeda não suportada
INVALID_PIX_KEY422Chave PIX malformada ou não encontrada no DICT
UNSUPPORTED_CHAIN422network não suportado para a moeda
INSUFFICIENT_FUNDS422Saldo insuficiente para amount + fee
BELOW_MIN_LIMIT409Abaixo do mínimo — details.min_amount
EXCEEDS_MAX_LIMIT409Acima do máximo — details.max_amount
LIMIT_EXCEEDED409Limite diário/mensal atingido
DUPLICATE_EXTERNAL_ID409external_id já utilizado
ACCOUNT_UNDER_REVIEW403Conta sob análise — operação suspensa
PROVIDER_ERROR502Erro no provedor — retryable

PIX (BRL)

cURL
PHP
JavaScript
Python
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"external_id":"saque_001","amount":50.00,"currency":"BRL","key":"12345678901","key_type":"cpf","description":"Saque PIX"}'
SIGNATURE=$(printf '%s' "$TIMESTAMP.$NONCE.$BODY" | openssl dgst -sha256 -hmac "$SIGNING_KEY" -hex | awk '{print $2}')

curl -X POST https://api.bspay.co/v2/transactions/cashout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -d "$BODY"

Cripto — body usa network:

BODY='{"external_id":"crypto_001","amount":50.00,"currency":"USDT","key":"TRwLhXvqNqTqbGgHNPCEfLeEfDwfWTpuxi","network":"tron"}'
# Mesma rotina HMAC do exemplo PIX

SPEI (MXN) — body usa CLABE + name + bank_code:

BODY='{"external_id":"spei_001","amount":200.00,"currency":"MXN","key":"012345678901234567","name":"Maria Lopez","bank_code":"BANORTE"}'
# Mesma rotina HMAC do exemplo PIX
202 PIX
202 Cripto
401 Signature
422 Funds
{
  "success": true,
  "data": {
    "transaction_id": "1e2da23478577eaedf6e0ad8dea877cb",
    "external_id": "saque_001",
    "currency": "BRL",
    "amount": 50.00,
    "fee": 1.00,
    "status": "pending",
    "created_at": "2026-04-30T14:02:48Z"
  },
  "message": "PENDING",
  "request_id": "d83a1af58da407fcc881c0af",
  "timestamp": "2026-04-30T14:02:48Z"
}

Fluxo assíncrono

  1. Você envia o request com HMAC válido
  2. API retorna 202 Accepted com status: pending (saldo já debitado)
  3. Servidor processa contra o provedor (PIX/blockchain/SPEI)
  4. Sucesso → webhook cashout.confirmed com hash (PIX e2e_id) ou tx_hash (blockchain)
  5. Falha → webhook cashout.failed com error_code específico, saldo refundado automaticamente

Esta página foi útil?