Saques

Saldo das contas e dinheiro saindo delas. Leia antes Saques e transferências: os saques pela API precisam estar ligados pelo dono e usam só destinos seguros.

Rotas

	Rota
`GET`	`/balances`	saldo de cada conta ativa no modo da chave
`POST`	`/payouts`	sacar (exige `Idempotency-Key`)
`GET`	`/payouts`	lista (`?status=`, `?provider_account_id=`)
`GET`	`/payouts/:id`	um saque
`POST`	`/payouts/:id/sync`	consultar a conta agora
`GET`	`/payout-destinations`	chaves Pix salvas (mascaradas)
`GET`	`/payout-settings`	`api_enabled` e `daily_limit`

Salvar chaves e mudar as regras é feito só no painel, pelo dono da empresa.

Sacar

curl https://api.suypay.com/v1/payouts \
  -H "Authorization: Bearer suy_live_..." \
  -H "Idempotency-Key: retirada-2026-10-18" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_account_id": "pa_...",
    "amount": 150000,
    "destination": { "type": "pix_key", "destination_id": "pdst_..." },
    "description": "Retirada de outubro"
  }'

Para a conta cadastrada no provedor, use "destination": { "type": "account" }.

{
  "id": "po_...",
  "object": "payout",
  "status": "processing",
  "amount": 150000,
  "fee": 50,
  "provider": "wyvipay",
  "destination": { "type": "pix_key", "key_type": "email", "key": "m***@empresa.com.br", "label": "Conta da Maria" },
  "uncertain": false,
  "failure_code": null,
  "failure_reason": null
}

Quando a conta não responde

A resposta vem com status: "processing" e uncertain: true. Não crie outro saque. A SuyPay consulta a conta de novo (pelo webhook dela, por POST /payouts/:id/sync e uma vez por dia). Nas contas que garantem que a mesma chave devolve a mesma transferência (Wyvi Pay, Pagmaster, ClownPay, Stripe), a SuyPay recupera o saque sozinha; nas outras, confira o extrato da conta.

Avisos

payout.created, payout.updated, payout.paid, payout.failed, payout.canceled e payout_destination.created chegam no seu webhook com o objeto payout (ou a chave salva, mascarada).