Solicitar Saque (Cash Out)

Solicite a transferência do seu saldo disponível para uma conta bancária via PIX. Esta rota gera um pedido de saque que será processado pela NomadPay.

POST/withdrawals

Descrição

Gera um pedido de saque. O valor solicitado é instantaneamente debitado do seu saldo disponível na plataforma (como Em Processamento). O saque será aprovado e transferido via PIX pela nossa equipe.

Parâmetros (Header)

Recomendado: Para evitar duplicidade de saques, é altamente recomendado o envio do cabeçalho Idempotency-Key.

Header	Obrigatório	Descrição
Idempotency-Key	Sim	Identificador único (UUID ou string) para evitar cobranças duplicadas em caso de retry.

Parâmetros (Body)

Parâmetro	Tipo	Obrigatório	Descrição
amount	number	Sim	O valor do saque em reais (ex: 100.50).
pix_key_type	string	Sim	O tipo da chave PIX. Valores aceitos: CPF, CNPJ, EMAIL, TELEFONE, ALEATORIA.
pix_key	string	Sim	A chave PIX correspondente ao tipo informado.

Exemplo de 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": "TELEFONE", "pix_key": "+55 11 98888-7777" }' ```

Fluxo de Status

O status do saque pode assumir os seguintes valores:

• PENDING: O saque foi solicitado, e o valor reservado.
• PROCESSING: O saque está sendo ativamente processado.
• PAID: O saque foi pago com sucesso na conta informada.
• FAILED: Ocorreu um erro técnico ao realizar o saque (valor estornado).
• CANCELLED: O saque foi cancelado pelo administrador (valor estornado).

Exemplo de Resposta (201 Created)

```json { "id": "wd_a1b2c3d4e5f6", "external_reference": "WDR_A1B2C3D4E5F67890", "company_id": "comp_xxxxxxx", "user_id": "usr_xxxxxxx", "amount": 250.00, "pix_key_type": "TELEFONE", "pix_key": "+55 11 98888-7777", "status": "PENDING", "created_at": "2026-06-27T17:00:00.000Z", "updated_at": "2026-06-27T17:00:00.000Z" } ```

Possíveis Erros

• 400 Bad Request - Saldo insuficiente, valor inválido ou chave PIX ausente.
• 401 Unauthorized - Chave de API (Secret) inválida ou ausente.
• 409 Conflict - Requisição duplicada para o mesmo Idempotency-Key com dados diferentes.