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 EnPixKeyType	não	necessário conceitualmente 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

Cuidado

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

Resposta (201) — WithdrawCreatedResponseDto:

{
  "id": "uuid",
  "status": "PENDING",
  "amount": 5000,
  "currency": "BRL",
  "pixKey": "chave@pix.com",
  "pixKeyType": "EMAIL",
  "creditorDocument": "12345678909",
  "creditorName": "João Silva",
  "isAutomatic": true,
  "createdAt": "2026-07-16T12:00:00.000Z"
}

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

GET /withdraws/merchant → 200

Lista os saques da empresa dona da chave, do mais recente para o mais antigo (paginação por cursor — ver seção 5). Requer scope READ_WITHDRAWS.

Query:

Campo	Tipo	Obrigatório	Regras / Default
status	enum EnWithdrawStatus	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": "chave@pix.com",
      "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://goldpay-goldpay-api.f0czp0.easypanel.host/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://goldpay-goldpay-api.f0czp0.easypanel.host/api/withdraws/merchant/<WITHDRAW_ID> \
  -H "X-Api-Key: <SECRET_KEY>"