POST

Solicitar Saque (Withdraw)

Solicita um saque do saldo disponível da empresa. Se a requisição incluir uma chave PIX (pixKey), ela será usada prioritariamente. Caso contrário, o sistema usará a chave PIX principal cadastrada no BankAccount da empresa.

Valores monetários

Sempre informados em centavos (R$ 25,00 → 2500)

Campo metadata (opcional)

A requisição agora aceita o campo metadata que pode ser string ou JSON (objeto). Se enviar um objeto, ele será salvo como string JSON no banco. É totalmente opcional e o metadata que você enviar será retornado no webhook.

Endpoint

POST/api/Withdraw/request

Solicita um saque do saldo disponível

Headers

Parametro	Tipo	Descricao
`Accept`obrigatorio	`string`	application/json
`Content-Type`obrigatorio	`string`	application/json
`X-Client-Id`obrigatorio	`string`	Client ID do aplicativo
`X-API-Key`obrigatorio	`string`	Secret Key (Company)
`Idempotency-Key`obrigatorio	`string`	Chave única (ex.: wd_123456789)

Request Body

request-body.json

json

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

Campos do Body

Parametro	Tipo	Descricao
`amount`obrigatorio	`integer`	Valor do saque em centavos (2500 = R$ 25,00)
`currency`obrigatorio	`string`	Moeda padrão (BRL)
`pixKey`	`string`	Chave PIX a ser usada (CPF, CNPJ, e-mail, telefone ou EVP). Opcional
`pixKeyType`	`string`	Tipo da chave PIX (ex: CPF, CNPJ, EMAIL, PHONE, EVP). Opcional
`description`	`string`	Descrição livre para o saque. Opcional
`metadata`	`string \| object`	Metadados personalizados. Pode ser string ou objeto JSON. Retorna no webhook. Opcional

Resposta de Sucesso (201 Created)

response.json

json

{
  "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:

error.json

json

{
  "message": "Chave PIX não encontrada. Cadastre sua conta bancária ou envie a PixKey no request."
}

Possíveis Erros

Código	Nome	Descrição
`400`	Bad Request	Erro de validação (ex.: amount <= 0, valor mínimo R$ 10,00)
`403`	Forbidden	Sem permissão para sacar (token sem escopo da empresa)
`409`	Conflict	Colisão de idempotência (mesma Idempotency-Key já usada)
`500`	Internal Server Error	Erro interno do servidor

Exemplos

cURL

bash

curl -X POST 'https://rayopay.com.br/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": "api", "pedidoId": 123 }
  }'

JavaScript / Node.js

javascript

const response = await fetch('https://rayopay.com.br/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: 'api', pedidoId: 123 }
  })
});
 
const data = await response.json();
console.log(data);

Observações

Se pixKey for omitida, o sistema automaticamente usará a chave PIX cadastrada na conta bancária (BankAccount) da empresa.
Se nenhuma chave estiver disponível, a API retornará erro.
O valor mínimo para saque é R$ 10,00 (1000 centavos).