Solicitar Saque

Solicita um saque do saldo disponivel da empresa. Se a requisicao incluir uma chave PIX (pixKey), ela sera usada prioritariamente.

POST/api/Withdraw/request

Headers

Header	Valor	Status
Content-Type	application/json	Obrigatorio
Accept	application/json	Obrigatorio
X-Client-Id	<client_id>	Obrigatorio
X-API-Key	<api_key>	Obrigatorio
X-Operation-Token	<token com scope cashout:create>	Obrigatorio

O header X-Operation-Token e obrigatorio e deve ser gerado no endpoint POST /api/v1/operation-auth/token com scope cashout:create. Veja a secao de Autenticacao para mais detalhes.

Observacao

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

Request Body

Body

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

Parametros

Parametro	Tipo	Descricao
`amount`*	number	Valor em centavos (2500 = R$ 25,00)
`currency`*	string	Moeda (BRL)
`pixKey`	string	Chave PIX de destino (opcional)
`pixKeyType`	string	Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP
`description`	string	Descricao do saque
`metadata`	object	Dados extras para referencia

amount

Obrigatorionumber

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

currency

Obrigatoriostring

Moeda (BRL)

pixKey

string

Chave PIX de destino (opcional)

pixKeyType

string

Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP

description

string

Descricao do saque

metadata

object

Dados extras para referencia

Response

Regra Importante

O response indica apenas se o pedido foi criado ou se falhou ao criar. Nao existe pending, awaiting ou processing no response de criacao. Esses status pertencem ao acompanhamento via webhook, provedor ou liquidacao PIX.

Sucesso

HTTP 201Created

Response 201

{
  "success": true,
  "status": "success",
  "message": "Pedido de saque criado com sucesso.",
  "id": 12345,
  "companyId": 10,
  "idempotencyKey": "wd_test_pix_custom",
  "value": 25.00,
  "pixKey": "********",
  "pixKeyType": "CPF",
  "creditorDocument": "********",
  "description": "Saque R$25 via chave custom",
  "currency": "BRL",
  "createdAt": "2026-06-14T16:50:00Z"
}

Campos do Sucesso

Parametro	Tipo	Descricao
`success`	boolean	Sempre true quando o pedido foi criado.
`status`	string	Sempre success quando o pedido foi criado.
`message`	string	Mensagem de confirmacao da criacao.
`id`	number	ID interno do pedido de saque.
`companyId`	number	ID da empresa.
`idempotencyKey`	string	Chave de idempotencia enviada no header Idempotency-Key.
`value`	number	Valor liquido do saque em reais.
`pixKey`	string	Chave PIX usada como destino.
`pixKeyType`	string	Tipo da chave PIX: CPF, CNPJ, EMAIL, PHONE ou EVP.
`creditorDocument`	string	Documento do favorecido.
`description`	string	Descricao enviada na requisicao.
`currency`	string	Moeda do saque. Atualmente BRL.
`createdAt`	string	Data/hora de criacao do pedido.

success

boolean

Sempre true quando o pedido foi criado.

status

string

Sempre success quando o pedido foi criado.

message

string

Mensagem de confirmacao da criacao.

id

number

ID interno do pedido de saque.

companyId

number

ID da empresa.

idempotencyKey

string

Chave de idempotencia enviada no header Idempotency-Key.

value

number

Valor liquido do saque em reais.

pixKey

string

Chave PIX usada como destino.

pixKeyType

string

Tipo da chave PIX: CPF, CNPJ, EMAIL, PHONE ou EVP.

creditorDocument

string

Documento do favorecido.

description

string

Descricao enviada na requisicao.

currency

string

Moeda do saque. Atualmente BRL.

createdAt

string

Data/hora de criacao do pedido.

Falha

Quando a API nao consegue criar o pedido de saque, ela retorna HTTP de erro. Nesses casos, o pedido nao deve ser considerado criado.

HTTP	Resultado	Exemplo de causa
400 Bad Request	Falha ao criar	Body ausente, amount invalido, saldo insuficiente, chave PIX invalida.
401 Unauthorized	Falha ao criar	Token de operacao invalido.
403 Forbidden	Falha ao criar	Credenciais invalidas, empresa nao permitida ou IP fora da whitelist.
409 Conflict	Falha ao criar	Conflito de idempotencia.
500 Internal Server Error	Falha ao criar	Erro interno ao solicitar saque.

Exemplos de Erro

Body ausente

400

{
  "message": "Body ausente."
}

Amount invalido

400

{
  "message": "Amount invalido (deve ser > 0, em centavos)."
}

Idempotency-Key ausente

400

{
  "message": "Header Idempotency-Key e obrigatorio."
}

Token de operacao invalido

401

{
  "title": "Token de operacao invalido.",
  "detail": "Token invalido ou expirado.",
  "header": "X-Operation-Token"
}

IP nao autorizado

403

{
  "title": "IP nao autorizado.",
  "detail": "O IP 177.123.45.67 nao esta na whitelist desta empresa."
}

Erro interno

500

{
  "message": "Erro ao solicitar saque."
}

Como Integrar

Use somente o HTTP status e o campo status do response de criacao.

Regra de integracao

HTTP 201 + status "success" = pedido criado
HTTP 400/401/403/409/500 = pedido nao criado

Nao aguarde uma segunda resposta HTTP para a mesma requisicao. Se o saque mudar de estado depois, essa atualizacao pertence ao fluxo de webhook ou consulta.

Exemplo cURL

cURL

# 1. Primeiro, gere o token de operacao
TOKEN=$(curl -s -X POST https://vorexy.com/api/v1/operation-auth/token \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -d '{"scopes": ["cashout:create"]}' | jq -r '.token')
# 2. Solicite o saque com o token
curl -X POST 'https://vorexy.com/api/Withdraw/request' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: <CLIENT_ID>' \
  -H 'X-API-Key: <API_KEY>' \
  -H "X-Operation-Token: $TOKEN" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "description": "Saque R$10 via chave custom",
    "metadata": { "origem": "n8n", "pedidoId": 123 }
  }'