Saque da subconta

Manda o saldo atribuído a uma subconta por Pix para a chave do cliente (a enviada ou a guardada na subconta).

POST /v1/subaccounts/{id}/withdrawals

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f/withdrawals \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: repasse-semana-41-vendedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "destination": { "keyType": "cpf", "key": "123.456.789-09" }, "description": "Repasse semanal" }'

200

{
  "id": "SAQ-API-5F6H1N0P2M4Q",
  "status": "processing",
  "amount": 9800,
  "fee": 50,
  "total": 9850,
  "channel": "api",
  "destination": { "name": "Ana S.", "institution": "Banco Exemplo", "keyType": "cpf", "key": "***.456.789-**" },
  "endToEndId": null,
  "failureReason": null,
  "createdAt": "2026-10-08T15:20:00.000Z",
  "completedAt": null
}

Escopo withdrawals:write, 2FA ligado na conta e IP liberado na chave de API. É um saque comum, com as mesmas regras de Pedir saque: amount sai da subconta, a sua taxa por saque paga a tarifa da WyzeCash (o que sobra fica com você; se ela não cobre, a tarifa sai do valor sacado) e o resto vai por Pix. Falhou ou foi recusado, o valor volta à subconta.

id · string · required

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

Idempotency-Key · string · required

8 a 128 caracteres, única por saque.

amount · integer · required

Valor em centavos que sai da subconta. Acima do saldo dela: INSUFFICIENT_SUBACCOUNT_BALANCE. Taxa maior que o valor: FEE_ABOVE_AMOUNT.

destination · object

{ "keyType": "cpf" | "cnpj" | "email" | "phone" | "random", "key": "..." }: a chave do cliente. Sem ela, vai para a pixKey guardada na subconta; sem nenhuma das duas: 422 DESTINATION_REQUIRED.

description · string

Até 140 caracteres.

​

Resposta

O formato de Pedir saque: amount é o que chega na chave (o valor menos a sua taxa por saque, ou menos a tarifa se a sua taxa for menor), fee a tarifa da WyzeCash. Os webhooks withdrawal.* avisam o resultado.

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts/sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f/withdrawals \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: repasse-semana-41-vendedor-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "destination": { "keyType": "cpf", "key": "123.456.789-09" }, "description": "Repasse semanal" }'

200

{
  "id": "SAQ-API-5F6H1N0P2M4Q",
  "status": "processing",
  "amount": 9800,
  "fee": 50,
  "total": 9850,
  "channel": "api",
  "destination": { "name": "Ana S.", "institution": "Banco Exemplo", "keyType": "cpf", "key": "***.456.789-**" },
  "endToEndId": null,
  "failureReason": null,
  "createdAt": "2026-10-08T15:20:00.000Z",
  "completedAt": null
}