3. Sacar saldo por Pix

Saque do saldo em reais da loja para uma chave Pix. A taxa é descontada do valor: amount sai do saldo e chega netAmountCents.

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  S->>G: GET /merchant/balance
  S->>G: GET /withdraws/merchant/quote?amount=50000
  G-->>S: feeTotalCents, netAmountCents
  S->>G: POST /withdraws/merchant (idempotencyKey no corpo)
  G-->>S: 201 PENDING/PROCESSING
  G-->>S: webhook withdraw.completed ou withdraw.failed

Passo 1 — Saldo

curl -s https://api.gestaotechnology.com/api/merchant/balance -H "X-Api-Key: <SECRET_KEY>"

Use total.available. Se um item de wallets vier com canWithdraw: false, o saque por ele não está disponível (cannotWithdrawReason).

Passo 2 — Cotar a taxa

curl -s "https://api.gestaotechnology.com/api/withdraws/merchant/quote?amount=50000" -H "X-Api-Key: <SECRET_KEY>"

{ "amountCents": 50000, "feeTotalCents": 350, "netAmountCents": 49650 }

Passo 3 — Pedir o saque

Scope CREATE_WITHDRAW. A idempotência é pelo campo idempotencyKey no corpo: use o id do saque no seu sistema. Sem pixKey, vai para a chave Pix padrão da empresa.

curl -X POST https://api.gestaotechnology.com/api/withdraws/merchant \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "idempotencyKey": "saque-2026-10-15-01"
  }'

{
  "id": "e4b7c2a1-9d3f-4e6b-8a5c-1f2d3e4a5b6c",
  "status": "PROCESSING",
  "kind": "PIX_KEY",
  "amount": 50000,
  "currency": "BRL",
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "creditorDocument": "12345678000199",
  "creditorName": "Sua Loja Ltda",
  "isAutomatic": true,
  "createdAt": "2026-10-15T14:00:00.000Z",
  "feeTotalCents": 350,
  "netAmountCents": 49650
}

Passo 4 — Webhook

{
  "event": "withdraw.completed",
  "occurredAt": "2026-10-15T14:00:41.000Z",
  "data": {
    "companyId": "c1d2e3f4-0000-4000-8000-000000000001",
    "withdrawId": "e4b7c2a1-9d3f-4e6b-8a5c-1f2d3e4a5b6c",
    "status": "COMPLETED",
    "amount": 50000,
    "currency": "BRL",
    "providerEndToEndId": "E00000000202610151400abcdef1234",
    "providerPaymentId": "psp-pay-91a",
    "providerTid": "psp-tid-77c"
  }
}

Em falha chega withdraw.failed com reason. Sem webhook, consulte GET /withdraws/merchant/e4b7c2a1-9d3f-4e6b-8a5c-1f2d3e4a5b6c (scope READ_WITHDRAWS).

Erros comuns

Situação	Resposta	O que fazer
Sem `pixKey` e sem chave padrão ativa	`404`	Informe `pixKey` e `pixKeyType` ou cadastre a chave padrão no painel.
`pixKey` sem `pixKeyType`	`400`	Envie os dois.
Reenvio com o mesmo `idempotencyKey`	o mesmo saque	Normal: nada é duplicado.
`idempotencyKey` já usado por outra empresa	`409 IDEMPOTENCY_KEY_CONFLICT`	Gere outra chave; prefira UUID.
O `POST` deu timeout, sem `id` na mão	—	`GET /withdraws/merchant/by-idempotency-key/<sua-chave>`: `200` = foi criado; `404` = reenvie com a mesma chave.

Referência: Saques, Saldo.