POST

Solicitar Saque (Withdraw)

Solicita um saque do saldo disponivel da empresa. Se a requisicao incluir uma chave PIX (pixKey), ela sera usada prioritariamente. Caso contrario, o sistema usara a chave PIX principal cadastrada no BankAccount da empresa.

Valores monetarios: Sempre informados em centavos (R$ 25,00 -> 2500)

NOVO - Campo metadata (opcional):

A requisicao agora aceita o campo metadata que pode ser string ou JSON (objeto). Se enviar um objeto, ele sera salvo como string JSON no banco.

E totalmente opcional e fica salvo no campo Withdraw.Metadata.

O metadata que voce enviar sera retornado no webhook.

Obs: Se pixKey for omitida, o sistema automaticamente usara a chave PIX cadastrada na conta bancaria (BankAccount) da empresa. Se nenhuma chave estiver disponivel, a API retornara erro.

Endpoint

POST /api/Withdraw/request

Headers

Header	Valor	Status
`Accept`	application/json	Obrigatorio
`Content-Type`	application/json	Obrigatorio
`X-Client-Id`	Client ID do aplicativo	Obrigatorio
`X-API-Key`	Secret Key (Company)	Obrigatorio
`Idempotency-Key`	Chave unica (ex.: wd_123456789)	Obrigatorio

Request Body

{
  "amount": 2500,
  "currency": "BRL",
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "description": "Saque teste via chave custom",
  "metadata": { "origem": "n8n", "pedidoId": 123 }
}

Campos do Body

amount(integer)Obrigatorio

Valor do saque em centavos (2500 = R$ 25,00)

currency(string)Obrigatorio

Moeda padrao (BRL)

pixKey(string)Opcional

Chave PIX a ser usada (CPF, CNPJ, e-mail, telefone ou EVP)

pixKeyType(string)Opcional

Tipo da chave PIX (ex: CPF, CNPJ, EMAIL, PHONE, EVP)

description(string)Opcional

Descricao livre para o saque

metadata(string | object)OpcionalNovo

Metadados personalizados. Pode ser uma string ou um objeto JSON. Se for objeto, sera convertido em string JSON. Retorna no webhook.

Resposta de Sucesso (201 Created)

{
  "id": 15,
  "companyId": 1,
  "idempotencyKey": "dc2b11dc8007409dbd421ed9014ac18c",
  "value": 10.00,
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "creditorDocument": "11111111111111",
  "description": "Saque teste via chave custom",
  "currency": "BRL",
  "enTransaction": "Awaiting",
  "createdAt": "2025-11-17T14:05:07.825Z"
}

Exemplo de Erro

Sem chave PIX cadastrada:

{
  "message": "Chave PIX nao encontrada. Cadastre sua conta bancaria ou envie a PixKey no request."
}

Possiveis Erros

400Bad Request- Erro de validacao (ex.: amount <= 0, valor minimo R$ 10,00)

403Forbidden- Sem permissao para sacar (token sem escopo da empresa)

409Conflict- Colisao de idempotencia (mesma Idempotency-Key ja usada)

500Internal Server Error- Erro interno do servidor

Exemplos

cURL

curl -X POST 'https://app.veltrixpagamentos.com/api/Withdraw/request' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: e1c98954cc404cbcb2868af9b40c7a33' \
  -H 'X-API-Key: sua-api-key-secreta' \
  -H 'Idempotency-Key: wd_test_pix_custom' \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "description": "Saque R$10 via chave custom",
    "metadata": { "origem": "n8n", "pedidoId": 123 }
  }'

JavaScript/Node.js

const response = await fetch('https://app.veltrixpagamentos.com/api/Withdraw/request', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-Client-Id': 'e1c98954cc404cbcb2868af9b40c7a33',
    'X-API-Key': 'sua-api-key-secreta',
    'Idempotency-Key': 'wd_test_' + Date.now()
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'BRL',
    pixKey: '50651470862',
    pixKeyType: 'CPF',
    description: 'Saque R$10 via chave custom',
    metadata: { origem: 'n8n', pedidoId: 123 }
  })
});

const data = await response.json();
console.log(data);

Observacoes

- Se pixKey for omitida, o sistema automaticamente usara a chave PIX cadastrada na conta bancaria (BankAccount) da empresa.

- Se nenhuma chave estiver disponivel, a API retornara erro.

- O valor minimo para saque e R$ 10,00 (1000 centavos).