Solicitar Saque (PIX Out)

Envie transferências PIX para qualquer chave, debitando diretamente do saldo disponível da sua conta NomadsPay.

POST/withdrawals

Descrição

Cria um pedido de saque PIX. O valor é debitado do saldo disponível e a transferência entra na fila de processamento para liquidação na chave PIX informada.

⚠️ Importante: Saques estão sujeitos à aprovação pela equipe NomadsPay. O valor é reservado imediatamente, mas a liquidação pode levar de alguns minutos até o próximo ciclo de processamento.

Parâmetros do Header

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <SEU_CLIENT_SECRET>`
`Idempotency-Key`	Sim	UUID único para evitar duplicatas — se a mesma chave for reenviada, o saque original é retornado sem criar um novo
`Content-Type`	Sim	`application/json`

Parâmetros do Body

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	`number`	Sim	Valor do saque em reais. Mínimo: `1.00`
`pix_key_type`	`string`	Sim	Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `TELEFONE` ou `ALEATORIA`
`pix_key`	`string`	Sim	A chave PIX de destino correspondente ao tipo informado

Resposta de Sucesso

Campo	Tipo	Descrição
`id`	`string`	ID único do saque
`amount`	`number`	Valor solicitado
`status`	`string`	`PENDING` — na fila de processamento
`pix_key`	`string`	Chave PIX de destino
`pix_key_type`	`string`	Tipo da chave informada
`queue_position`	`number`	Posição na fila de saques
`idempotency_key`	`string`	Chave de idempotência enviada
`created_at`	`string`	Data/hora de criação

Ciclo de Status do Saque

Status	Descrição
`PENDING`	Na fila — valor reservado do saldo
`PROCESSING`	Sendo processado pelo banco
`PAID`	Liquidado com sucesso na chave PIX
`FAILED`	Falha bancária — valor devolvido ao saldo
`CANCELLED`	Cancelado — valor devolvido ao saldo

Códigos de Erro

Código	Motivo
`400`	Saldo insuficiente, valor inválido, chave PIX ausente ou formato inválido
`401`	Token inválido ou ausente
`409`	Saque duplicado — `Idempotency-Key` já usada
`500`	Erro interno

Requisição

bash

curl -X POST https://api.nomadspay.com/withdrawals \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-1234567890ab" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "pix_key_type": "EMAIL",
    "pix_key": "seu@email.com"
  }'

Resposta (201 Created)

json

{
  "id": "wd_a1b2c3d4e5f6",
  "amount": 250.00,
  "status": "PENDING",
  "pix_key": "seu@email.com",
  "pix_key_type": "EMAIL",
  "queue_position": 1,
  "idempotency_key": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "created_at": "2024-01-01T12:00:00.000Z"
}

Exemplo em JavaScript

javascript

const response = await fetch('https://api.nomadspay.com/withdrawals', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NOMADS_SECRET}`,
    'Idempotency-Key': crypto.randomUUID(), // gera UUID único por requisição
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 250.00,
    pix_key_type: 'EMAIL',
    pix_key: 'seu@email.com'
  })
});

if (response.status === 400) {
  const err = await response.json();
  console.error('Erro:', err.error); // ex: "Saldo insuficiente"
}

const withdrawal = await response.json();
console.log('Saque criado:', withdrawal.id, '| Posição na fila:', withdrawal.queue_position);

Exemplo em Python

python

import os, uuid, requests

secret = os.getenv("NOMADS_SECRET")

resp = requests.post(
    "https://api.nomadspay.com/withdrawals",
    headers={
        "Authorization": f"Bearer {secret}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json"
    },
    json={
        "amount": 250.00,
        "pix_key_type": "EMAIL",
        "pix_key": "seu@email.com"
    }
)

if resp.status_code == 400:
    print("Erro:", resp.json().get("error"))
else:
    withdrawal = resp.json()
    print(f"Saque {withdrawal['id']} criado — posição {withdrawal['queue_position']}")

Webhooks do Saque

Sua aplicação receberá notificações automáticas na URL de webhook configurada a cada mudança de status:

Evento	Quando é disparado
`withdrawal.pending`	Imediatamente após a criação
`withdrawal.processing`	Quando sai da fila e entra em processamento
`withdrawal.paid`	PIX liquidado com sucesso
`withdrawal.failed`	Erro bancário — campo `reason` indica o motivo
`withdrawal.cancelled`	Cancelado — valor devolvido ao saldo

Para mais detalhes sobre validação de assinatura e estrutura dos webhooks, consulte a documentação de Webhooks.

❓ Dúvidas frequentes — Saque PIX

Como saber se o saque foi concluído com sucesso?

Monitore via webhook. Quando o saque for liquidado, você receberá o evento withdrawal.paid com a confirmação. O payload incluirá o id do saque, o valor e o status final.

Se não usar webhook, consulte periodicamente o status pelo painel em app.nomadspay.com → Saques ou via GET /withdrawals/:id (se disponível na sua conta).

O que é o Idempotency-Key e por que é obrigatório?

É uma chave única (UUID) que você gera por requisição. Se sua rede cair após enviar o POST e você não souber se o saque foi criado, pode reenviar a mesma requisição com a mesma Idempotency-Key — a API retorna o saque original sem criar um duplicado.

Nunca reutilize a mesma chave para saques diferentes. Gere um novo UUID para cada tentativa de saque.

javascript

// ✅ Correto — novo UUID por saque
const idempotencyKey = crypto.randomUUID();

// ❌ Errado — chave fixa causará erro no segundo saque
const idempotencyKey = 'minha-chave-fixa';

Recebi erro 400 "Saldo insuficiente". Como verificar meu saldo?

Consulte seu saldo disponível antes de solicitar o saque:

bash

curl https://api.nomadspay.com/charges/balance \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>"

Lembre-se: o saldo disponível já desconta saques pendentes e valores em processamento. Só solicite saques de valores que efetivamente estão no saldo retornado por essa rota.

Qual o tipo correto para minha chave PIX?

Tipo de chave	`pix_key_type`	Formato do `pix_key`
CPF	`CPF`	`123.456.789-00` ou `12345678900`
CNPJ	`CNPJ`	`12.345.678/0001-99` ou `12345678000199`
E-mail	`EMAIL`	`seu@email.com`
Telefone	`TELEFONE`	`+5511999999999`
Chave aleatória	`ALEATORIA`	UUID no formato `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

Se o tipo informado não corresponder ao formato da chave, o saque será rejeitado com 400.

O saque falhou. O que acontece com o dinheiro?

Quando o status muda para FAILED, o valor é automaticamente devolvido ao saldo disponível da sua conta. Você receberá o webhook withdrawal.failed com o motivo da falha no campo reason.

Causas comuns de falha:

Chave PIX inválida ou inexistente
Chave PIX encerrada pela instituição
Banco destino indisponível momentaneamente

Após a devolução, você pode tentar novamente com uma nova Idempotency-Key.

Quanto tempo leva para o saque ser processado?

O tempo varia conforme a fila de processamento. Em horário comercial, a maioria dos saques é processada em minutos. Fora do horário bancário, pode levar até o próximo ciclo.

Acompanhe o status via webhook — você será notificado imediatamente quando mudar de PENDING para PROCESSING e depois para PAID ou FAILED.

Posso cancelar um saque depois de criado?

O cancelamento depende do status atual. Saques com status PENDING (ainda na fila) podem ser cancelados pelo painel em app.nomadspay.com → Saques. Saques com status PROCESSING ou PAID não podem ser cancelados, pois já estão em trânsito ou liquidados.

Posso automatizar saques recorrentes (ex: saque diário automático)?

Sim. Crie um job agendado (cron) no seu backend que:

Consulta o saldo com GET /charges/balance
Se o saldo for maior que o mínimo desejado, cria o saque com POST /withdrawals
Gera um novo Idempotency-Key (UUID) a cada execução
Aguarda o webhook withdrawal.paid para confirmação

Certifique-se de tratar o erro 400 por saldo insuficiente no caso de o saldo ser zero.

Solicitar Saque (PIX Out) ​

Descrição ​

Parâmetros do Header ​

Parâmetros do Body ​

Resposta de Sucesso ​

Ciclo de Status do Saque ​

Códigos de Erro ​

Requisição ​

Resposta (201 Created) ​

Exemplo em JavaScript ​

Exemplo em Python ​

Webhooks do Saque ​

❓ Dúvidas frequentes — Saque PIX ​