Split

Requer autenticação

Distribua o valor de uma transação entre múltiplas contas automaticamente. Adicione o campo split a qualquer cashin ou cashout — a BSPAY faz a divisão na liquidação.

Parâmetros

splitarrayobrigatório

Lista de destinatários do split.

split[].usernamestringobrigatório

Username BSPay da conta destinatária.

split[].percentagenumber

Percentual do valor bruto (0.1–95).

split[].typestring

"fixed" para valor fixo.

split[].amountnumber

Valor fixo (obrigatório quando type: "fixed").

Regras

Soma dos percentuais ≤ 95% (saldo mínimo 5% na conta principal)
Mistura de fixo + percentual permitida
Todas as contas devem existir e estar ativas
Processado após liquidação da transação principal

Erros

Código	HTTP	Descrição
`INVALID_SPLIT_CONFIG`	422	Configuração inválida — veja `details.reason`
`SPLIT_EXCEEDS_MAX`	422	Soma de percentuais excede 95%
`SPLIT_BELOW_MIN`	422	Percentual abaixo de 0.1%
`USER_NOT_FOUND`	404	Username do split não encontrado
`USER_INACTIVE`	403	Conta destinatária inativa

cURL

PHP

JavaScript

Python

curl -X POST https://api.bspay.co/v2/transactions/cashin \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"currency":"BRL","split":[{"username":"partner1","percentage":30},{"username":"partner2","percentage":20}]}'

Marketplace — múltiplos destinos

{
  "amount": 1000.00,
  "currency": "BRL",
  "external_id": "order_mkt_001",
  "split": [
    { "username": "seller_a",   "percentage": 60 },
    { "username": "seller_b",   "percentage": 20 },
    { "username": "platform",   "type": "fixed", "amount": 50.00 }
  ]
}

Resposta 200 — confirmação do split

{
  "success": true,
  "data": {
    "transaction_id": "abc123",
    "external_id": "order_mkt_001",
    "amount": 1000.00,
    "currency": "BRL",
    "split": [
      { "username": "seller_a", "percentage": 60, "amount_credited": 600.00 },
      { "username": "seller_b", "percentage": 20, "amount_credited": 200.00 },
      { "username": "platform", "type": "fixed",  "amount_credited": 50.00 }
    ],
    "remainder_credited": 150.00,
    "status": "pending"
  }
}

Distribuição efetiva

{
  "seller_a":      "R$ 600,00 (60%)",
  "seller_b":      "R$ 200,00 (20%)",
  "platform":      "R$  50,00 (fixo)",
  "conta_principal": "R$ 150,00 (resto)"
}

Resposta de Erro (422)

{
  "success": false,
  "error": {
    "code": "SPLIT_EXCEEDS_MAX",
    "message": "Sum of percentages exceeds 95%.",
    "group": "VALIDATION",
    "retryable": false,
    "details": {
      "total_percentage": 110,
      "max_allowed": 95
    }
  }
}

AnteriorCash-outPróximoConsultar Saldo