Saques (PIX OUT)

POST /withdraws/merchant → 201

Solicita um saque PIX OUT. Requer scope CREATE_WITHDRAW.

Body:

Campo	Tipo	Obrigatório	Regras / Default
amount	int	sim	positivo (centavos)
currency	string	não	3 chars; default "BRL"
pixKey	string	não	1–255; se omitido, usa a chave PIX padrão ativa da empresa
pixKeyType	enum CPF | CNPJ | EMAIL | PHONE | RANDOM	condicional	obrigatório quando pixKey é informado
creditorDocument	string	não	11–14 (CPF/CNPJ); default = documento da chave PIX padrão
creditorName	string	não	1–255
idempotencyKey	string	sim	1–255
providerId	uuid	não	PSP específico; use o mesmo da cotação (abaixo) para que a taxa cotada seja a cobrada

Cuidado

Se pixKey for omitido e não houver chave PIX padrão ativa → 404 Not Found.

Resposta (201):

{
  "id": "uuid",
  "status": "PENDING",
  "amount": 5000,
  "currency": "BRL",
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "creditorDocument": "12345678909",
  "creditorName": "João Silva",
  "isAutomatic": true,
  "createdAt": "2026-07-16T12:00:00.000Z",
  "kind": "PIX_KEY",
  "feeTotalCents": 150,
  "netAmountCents": 4850
}

A taxa do saque é descontada do valor: amount sai do saldo e o destinatário recebe netAmountCents. kind é PIX_KEY (saque para chave).

status inicial é PENDING ou PROCESSING. O resultado final chega via webhook (withdraw.completed / withdraw.failed). isAutomatic indica se foi enviado automaticamente ao PSP.

Idempotência: reenviar com o mesmo idempotencyKey devolve o saque já criado, sem duplicar. A chave precisa ser única na plataforma, não só na sua empresa: use um UUID ou um id seu com prefixo. Uma chave já usada por outra empresa, ou num pagamento de QR Code, recebe 409 com errorCode: "IDEMPOTENCY_KEY_CONFLICT" — gere uma chave nova.

GET /withdraws/merchant/quote → 200

Cotação da taxa antes de sacar: quanto será descontado e quanto chega ao destinatário. Requer scope READ_WITHDRAWS. Mesmo cálculo do pedido.

Query	Tipo	Obrigatório	Regras
amount	int	sim	valor bruto em centavos
providerId	uuid	não	PSP específico (padrão: o da empresa)

Cotar um saque

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

{ "amountCents": 5000, "feeTotalCents": 150, "netAmountCents": 4850 }

GET /withdraws/merchant → 200

Lista os saques da empresa dona da chave, do mais recente para o mais antigo (paginação por cursor — ver Paginação). Cada item traz kind: PIX_KEY (saque para chave) ou BR_CODE (pagamento de QR Code). Requer scope READ_WITHDRAWS.

Query:

Campo	Tipo	Obrigatório	Regras / Default
status	enum	não	PENDING | PROCESSING | CONFIRMED | COMPLETED | FAILED | CANCELED | REVERSED
startDate	string (ISO 8601)	não	filtra createdAt >=
endDate	string (ISO 8601)	não	filtra createdAt <= (comparação literal — não é estendida até o fim do dia)
limit	int	não	máx 100, default 50
cursor	string	não	cursor opaco da página seguinte

Resposta (200):

{
  "items": [
    {
      "id": "uuid",
      "status": "COMPLETED",
      "amount": 5000,
      "currency": "BRL",
      "pixKey": "[email protected]",
      "pixKeyType": "EMAIL",
      "creditorDocument": "12345678909",
      "creditorName": "João Silva",
      "providerEndToEndId": "E00000000202601011200abcdef1234",
      "createdAt": "2026-07-16T12:00:00.000Z",
      "updatedAt": "2026-07-16T12:05:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Exemplo — listar saques concluídos a partir de uma data:

Listar saques

curl -s https://api.gestaotechnology.com/api/withdraws/merchant \
  -H "X-Api-Key: <SECRET_KEY>" \
  --get \
  --data-urlencode "status=COMPLETED" \
  --data-urlencode "startDate=2026-07-01T00:00:00.000Z" \
  --data-urlencode "limit=50"

GET /withdraws/merchant/:id → 200

Consulta um saque específico pelo ID. Requer scope READ_WITHDRAWS. De outra empresa ou inexistente → 404.

Resposta (200): os mesmos campos do item de listagem acima, mais providerPaymentId e providerTid (ambos string | null).

Consultar saque

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

GET /withdraws/merchant/by-idempotency-key/:key → 200

Consulta um saque pelo idempotencyKey que você mandou ao criá-lo. Serve para quando o POST deu timeout e você não recebeu o id: descubra se o saque foi criado antes de decidir reenviar. Requer scope READ_WITHDRAWS. Nenhum saque da sua empresa com essa chave → 404.

Resposta (200): o mesmo formato de GET /withdraws/merchant/:id.

Consultar saque pela chave

curl -s https://api.gestaotechnology.com/api/withdraws/merchant/by-idempotency-key/saque-2026-10-15-01 \
  -H "X-Api-Key: <SECRET_KEY>"

Passo a passo com webhooks: Guia › Sacar saldo por Pix.