Enviar para a subconta

Passa parte do seu saldo livre para uma subconta, sem tarifa.

POST /v1/subaccounts/{id}/fund

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42/fund \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: bonus-2026-10-vendedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500, "description": "Bônus de indicação" }'

200

{
  "id": "SUB-8M4Z3F7K9Q2W",
  "kind": "fund",
  "kindTitle": "Enviado da principal",
  "direction": "credit",
  "amount": 2500,
  "gross": null,
  "fee": 0,
  "description": "Bônus de indicação",
  "createdAt": "2026-10-08T15:40:00.000Z",
  "subaccount": { "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f", "externalId": "vendedor-42", "balance": 11700 }
}

Escopo subaccounts:write. Não há Pix nem tarifa: o dinheiro continua no seu saldo e passa a ser do cliente (um movimento SUB- do tipo fund). Só sai do seu saldo livre: o que já é das subcontas não conta.

id · string · required

sacc_ + 32 hex ou o seu externalId. Desativada: 422 SUBACCOUNT_INACTIVE.

Idempotency-Key · string · required

8 a 128 caracteres, única por envio. Repetir com os mesmos dados devolve o mesmo movimento; com outros dados, 422 IDEMPOTENCY_KEY_REUSED.

amount · integer · required

Valor em centavos. Acima do seu saldo livre (free em GET /v1/balance): 422 SUBACCOUNT_FUNDS.

description · string

Até 140 caracteres. Sem ela: “Enviado da conta principal”.

​

Resposta

O movimento criado, no formato de Movimentos da subconta (kind: "fund", direction: "credit"), mais subaccount com o saldo dela depois. O webhook subaccount.credited avisa.

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42/fund \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: bonus-2026-10-vendedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500, "description": "Bônus de indicação" }'

200

{
  "id": "SUB-8M4Z3F7K9Q2W",
  "kind": "fund",
  "kindTitle": "Enviado da principal",
  "direction": "credit",
  "amount": 2500,
  "gross": null,
  "fee": 0,
  "description": "Bônus de indicação",
  "createdAt": "2026-10-08T15:40:00.000Z",
  "subaccount": { "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f", "externalId": "vendedor-42", "balance": 11700 }
}