Transferir entre subcontas

Passa saldo de uma subconta para outra sua, sem tarifa.

POST /v1/subaccounts/{id}/transfer

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42/transfer \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: repasse-2026-09-fornecedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "to": "vendedor-77", "amount": 2000, "description": "Repasse de setembro" }'

200

{
  "id": "SUB-4Z3F7K9Q2W8M",
  "kind": "transfer",
  "kindTitle": "Transferência entre subcontas",
  "direction": "debit",
  "amount": 2000,
  "gross": null,
  "fee": 0,
  "description": "Repasse de setembro",
  "createdAt": "2026-10-08T15:20:00.000Z",
  "subaccount": { "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f", "externalId": "vendedor-42", "balance": 3000 },
  "to": { "id": "sacc_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e", "externalId": "vendedor-77", "balance": 2000 }
}

Escopo subaccounts:write. Não há Pix nem tarifa: o valor sai de uma subconta e entra na outra (dois movimentos SUB- do tipo transfer, um em cada). As duas precisam ser suas, estar ativas e ser diferentes.

id · string · required

Subconta de origem: sacc_ + 32 hex ou o seu externalId.

Idempotency-Key · string · required

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

to · string · required

Subconta de destino: sacc_... ou externalId. Não encontrada: 404 DESTINATION_NOT_FOUND. A mesma da origem: 422 SAME_SUBACCOUNT. Alguma desativada: 422 SUBACCOUNT_INACTIVE.

amount · integer · required

Valor em centavos. Acima do saldo da origem: 422 INSUFFICIENT_SUBACCOUNT_BALANCE.

description · string

Até 140 caracteres. Sem ela, cada lado mostra o nome da outra subconta (“Para Ateliê da Ana”, “De Ateliê da Ana”).

​

Resposta

O movimento de saída da origem, no formato de Movimentos da subconta, mais subaccount (origem) e to (destino), cada um com o saldo depois. Os webhooks subaccount.debited (origem) e subaccount.credited (destino) avisam.

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42/transfer \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: repasse-2026-09-fornecedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "to": "vendedor-77", "amount": 2000, "description": "Repasse de setembro" }'

200

{
  "id": "SUB-4Z3F7K9Q2W8M",
  "kind": "transfer",
  "kindTitle": "Transferência entre subcontas",
  "direction": "debit",
  "amount": 2000,
  "gross": null,
  "fee": 0,
  "description": "Repasse de setembro",
  "createdAt": "2026-10-08T15:20:00.000Z",
  "subaccount": { "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f", "externalId": "vendedor-42", "balance": 3000 },
  "to": { "id": "sacc_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e", "externalId": "vendedor-77", "balance": 2000 }
}