Pedir um saque

Registra o pedido e devolve 202: o pagamento é despachado depois, fora do ciclo do pedido. O saldo é reservado na mesma transação.

POSThttps://api.navenaut.com/payout/request

Autenticação

A sessão do painel autentica esta rota, e ela é lida de forma autoritativa: não há parâmetro em que o chamador aponte para outra conta.

Esta rota não exige escopo nomeado — o que não quer dizer que ela seja aberta: sem a credencial acima ela recusa.

Exige sessão de vendedor. O saldo cotado e sacado é sempre o da sessão: não há campo em que o chamador escolha outra conta.

Parâmetros

Corpo da requisição

application/json.

Campo	Tipo	Descrição
`amountCents`obrigatório	inteiro (centavos)	Quanto sacar, em centavos inteiros. Precisa caber no teto que a cotação devolveu.
`currency`obrigatório	um de: `BRL`, `USD`, `EUR`	A moeda do saque.
`reference`obrigatório	texto	Sua referência para este saque: letras, números, hífen e sublinhado, até 64 caracteres.

{
  "amountCents": 129900,
  "currency": "BRL",
  "reference": "exemplo"
}

Respostas

202 · aceito para processamento

{
  "legCount": 1,
  "legs": [
    {
      "amountCents": 129900,
      "dispatch": 1,
      "dispatchLabel": "exemplo",
      "feeBearer": "seller",
      "feeCents": 129900
    }
  ],
  "reference": "exemplo"
}

Pedido aceito e saldo reservado. O 202 fala da EXECUÇÃO, e o pagamento sai depois, num host próprio, fora do ciclo desta chamada. Ele não diz nada sobre quando um saldo ainda não liberado libera. Esse outro prazo é o de pending.releaseDates, em GET /seller/balance, e os dois não são a mesma coisa.

403 · proibido

O cadastro ainda não permite sacar, e reason diz o que falta: nunca enviado, ainda não aprovado, vencido, ou fora do limite da conta.

409 · conflito

Esta reference já foi usada nesta conta. Se foi retentativa de rede, o saque original está de pé; consulte-o antes de cunhar outra.

429 · excesso de chamadas

O teto MENSAL de saque desta conta fechou. Não é excesso de chamadas: é limite de VALOR, e a resposta traz o teto e o quanto do mês já foi usado.

503 · indisponível

O saque não pôde ser aceito, e reason nomeia qual condição bloqueou: o valor não cabe no que está disponível para saque, ficou abaixo do mínimo, o valor pedido não é positivo, ou falta preço cadastrado para montar o pagamento. Nada foi reservado.

Erros desta rota

Status	Código	Quando	O que fazer
403	`KYC_BLOCKED`	O cadastro desta conta ainda não permite sacar, e `reason` diz o que falta: nunca enviado, ainda não aprovado, vencido, ou fora do limite da conta.	Conclua no cadastro o que `reason` aponta. Repetir o saque antes disso devolve sempre 403, e nada foi reservado.
409	`PAYOUT_DUPLICATE`	Esta `reference` já foi usada nesta conta. É o que impede que uma retentativa de rede vire dois saques do mesmo dinheiro.	Consulte o saque original antes de cunhar outra referência: se ele está de pé, o dinheiro já está a caminho e nada precisa ser refeito.
409	`PAYOUT_PIX_KEY_REPLACEMENT_REQUIRED`	A chave Pix cadastrada era a do documento anterior: o suporte corrigiu o documento do vendedor e a chave deixou de valer. A recusa vem antes de qualquer reserva, então o saldo não muda, e a resposta traz só o código e a mensagem.	Cadastre uma nova chave Pix (que seja o documento corrigido, ou de outro tipo, como e-mail) e peça o saque de novo. Repetir o pedido antes disso devolve sempre 409.
429	`PAYOUT_MONTHLY_CEILING`	O teto MENSAL de saque desta conta fechou. Não é excesso de chamadas: é limite de VALOR, e a resposta traz o teto e o quanto do mês já foi usado.	Peça um valor que caiba no que resta do mês, ou espere a virada do mês civil. Espaçar as chamadas não muda nada, porque o limite não é de frequência.
503	`WITHDRAWAL_BLOCKED`	O saque não pôde ser aceito, e `reason` nomeia a condição: o valor não cabe no que está disponível, ficou abaixo do mínimo, não é positivo, ou falta preço cadastrado para montar o pagamento. Nada foi reservado.	Leia `reason`: as três primeiras se resolvem pedindo outro valor; a última é do nosso lado, e reenviar não resolve.

Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.