Saques (Withdrawals)

Endpoints para criar e consultar saques via PIX.

POST /v1/withdrawals

Cria um novo saque via API com suporte a idempotência.

Headers

http

Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {unique_key}

IMPORTANTE

O header Idempotency-Key é obrigatório para prevenir duplicação de saques. Use um UUID v4 ou string única.

Request Body

Campo	Tipo	Obrigatório	Descrição
`amount`	number	✅ Sim	Valor do saque em reais (ex: 10.00)
`pix_key`	string	⚠️ Condicional	Chave PIX de destino (obrigatório se não configurada no sistema)
`pix_key_type`	string	⚠️ Condicional	Tipo da chave PIX (`cpf`, `cnpj`, `phone`, `random`, `email`) (obrigatório se não configurada no sistema)
`authorize`	boolean	✅ Sim	Se deve tentar auto-aprovar o saque (true)

NOTA

Os campos pix_key e pix_key_type são condicionais: são obrigatórios apenas se o merchant não tiver uma chave PIX configurada no sistema. Se já houver uma chave configurada, esses campos são opcionais e, se fornecidos, sobrescrevem a chave padrão para este saque específico.

Exemplo de Request

bash

curl -X POST https://api.misespay.com/v1/withdrawals \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": 10.00,
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "authorize": true
  }'

Response (201 Created)

json

{
  "success": true,
  "message": "Saque solicitado com sucesso",
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "processing",
    "origin": "api",
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "e2e_id": null,
    "created_at": "2025-12-26T11:50:03-03:00"
  }
}

Response (200 OK - Idempotente)

Se a mesma Idempotency-Key for enviada novamente:

json

{
  "success": true,
  "message": "Saque já processado anteriormente",
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "processing",
    "origin": "api",
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "e2e_id": null,
    "created_at": "2025-12-26T11:50:03-03:00"
  },
  "idempotent": true
}

Campos da Resposta

Campo	Tipo	Descrição
`success`	boolean	Indica se a operação foi bem-sucedida
`message`	string	Mensagem descritiva
`data.withdrawal_id`	string (UUID)	ID único do saque
`data.amount`	string	Valor do saque formatado
`data.fee_amount`	string	Taxa cobrada formatada
`data.net_amount`	string	Valor líquido (após taxa) formatado
`data.status`	string	Status do saque (ver abaixo)
`data.origin`	string	Origem do saque ("api", "portal")
`data.pix_key`	string	Chave PIX de destino
`data.pix_key_type`	string	Tipo da chave PIX
`data.requires_merchant_approval`	boolean	Se requer aprovação manual do merchant
`data.requires_compliance_review`	boolean	Se requer revisão de compliance
`data.e2e_id`	string ou null	ID end-to-end do PIX (após processamento)
`data.created_at`	string (ISO 8601)	Data/hora de criação
`idempotent`	boolean	Presente apenas em respostas idempotentes

Status do Saque

Status	Descrição
`pending`	Aguardando aprovação
`processing`	Em processamento
`paid`	Saque concluído com sucesso
`failed`	Falha no processamento

Erros Possíveis

Cenários de teste (payloads)

Use os payloads abaixo para simular erros comuns durante a integração.

Endpoint	Cenário	Status esperado
`POST /v1/withdrawals`	Idempotency-Key ausente	`400`
`POST /v1/withdrawals`	Idempotency-Key inválido	`400`
`POST /v1/withdrawals`	Chave PIX não configurada	`400`
`POST /v1/withdrawals`	`amount` ausente	`422`
`POST /v1/withdrawals`	`authorize` ausente	`422`
`POST /v1/withdrawals`	`amount` inválido (0 ou negativo)	`422`
`POST /v1/withdrawals`	`pix_key_type` inválido	`422`
`POST /v1/withdrawals`	`pix_key` sem `pix_key_type`	`422`
`POST /v1/withdrawals`	`pix_key_type` sem `pix_key`	`422`
`POST /v1/withdrawals`	CPF inválido	`422`
`POST /v1/withdrawals`	Saldo insuficiente	`422`
`GET /v1/withdrawals/:id`	Saque não encontrado	`404`

POST /v1/withdrawals - 400 Idempotency-Key Ausente

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Resposta esperada:

json

{
  "success": false,
  "message": "Header Idempotency-Key é obrigatório",
  "errors": {
    "idempotency_key": ["Header Idempotency-Key é obrigatório"]
  }
}

POST /v1/withdrawals - 400 Idempotency-Key Inválido

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: invalid@key#with$special%chars
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Resposta esperada:

json

{
  "success": false,
  "message": "Idempotency-Key inválido. Use apenas letras, números, hífens e underscores (máximo 255 caracteres)",
  "errors": {
    "idempotency_key": ["Idempotency-Key inválido..."]
  }
}

POST /v1/withdrawals - 400 Chave PIX Não Configurada

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-no-pix-key
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Resposta esperada:

json

{
  "success": false,
  "message": "Chave PIX não configurada. Configure sua chave PIX ou forneça uma chave PIX customizada na requisição.",
  "errors": {
    "pix_key": ["Chave PIX não configurada..."]
  }
}

POST /v1/withdrawals - 422 Campo amount Ausente

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-no-amount
  Content-Type: application/json

Body:
{
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "amount": ["O valor do saque é obrigatório"]
  }
}

POST /v1/withdrawals - 422 Campo authorize Ausente

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-no-authorize
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "authorize": ["O parâmetro authorize é obrigatório"]
  }
}

POST /v1/withdrawals - 422 amount Menor/Igual a Zero

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-negative-amount
  Content-Type: application/json

Body:
{
  "amount": 0.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "amount": ["O valor do saque deve ser maior que zero"]
  }
}

POST /v1/withdrawals - 422 pix_key_type Inválido

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-invalid-pix-type
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "invalid_type"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "pix_key_type": [
      "O tipo de chave PIX deve ser: cpf, cnpj, email, phone ou random"
    ]
  }
}

POST /v1/withdrawals - 422 pix_key sem pix_key_type

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-pix-no-type
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "12345678901"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "pix_key_type": [
      "O tipo de chave PIX é obrigatório quando a chave PIX é fornecida"
    ]
  }
}

POST /v1/withdrawals - 422 pix_key_type sem pix_key

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-type-no-pix
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "pix_key": [
      "A chave PIX é obrigatória quando o tipo de chave PIX é fornecido"
    ]
  }
}

POST /v1/withdrawals - 422 CPF Inválido

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-invalid-cpf
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "11111111111",
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Dados inválidos",
  "errors": {
    "pix_key": ["CPF inválido"]
  }
}

POST /v1/withdrawals - 422 Saldo Insuficiente

json

Headers:
  Authorization: Bearer {seu_token_jwt}
  Idempotency-Key: test-insufficient-balance
  Content-Type: application/json

Body:
{
  "amount": 999999.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Resposta esperada:

json

{
  "success": false,
  "message": "Saldo insuficiente. Disponível: R$ X,XX | Necessário: R$ Y,YY",
  "errors": {
    "balance": ["Saldo insuficiente. Disponível: R$ X,XX | Necessário: R$ Y,YY"]
  }
}

GET /v1/withdrawals/:id - 404 Saque Não Encontrado

json

GET /v1/withdrawals/00000000-0000-0000-0000-000000000000

Headers:
  Authorization: Bearer {seu_token_jwt}

Resposta esperada:

json

{
  "success": false,
  "message": "Saque não encontrado",
  "errors": {
    "withdrawal": ["Saque não encontrado"]
  }
}

GET /v1/withdrawals/:id

Busca os detalhes de um saque específico pelo ID.

Headers

http

Authorization: Bearer {access_token}

Path Parameters

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID do saque

Exemplo de Request

bash

curl -X GET https://api.misespay.com/v1/withdrawals/881c686a-9e53-4809-a63c-c2730b924ea7 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

json

{
  "success": true,
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "paid",
    "origin": "api",
    "pix_key": "11999887766",
    "pix_key_type": "phone",
    "e2e_id": "E12345678202512261150abc123def456",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "bank_processing_status": "completed",
    "auto_approved": true,
    "compliance_status": "not_required",
    "processed_at": "2025-12-26T11:50:10-03:00",
    "created_at": "2025-12-26T11:50:03-03:00"
  }
}

Campos da Resposta

Campo	Tipo	Descrição
`withdrawal_id`	string (UUID)	ID único do saque
`amount`	string	Valor do saque formatado (ex: "R$ 10,00")
`fee_amount`	string	Taxa cobrada formatada (ex: "R$ 0,20")
`net_amount`	string	Valor líquido formatado (ex: "R$ 9,80")
`status`	string	Status do saque (ver tabela acima)
`origin`	string	Origem do saque ("api", "portal")
`pix_key`	string	Chave PIX de destino
`pix_key_type`	string	Tipo da chave PIX
`e2e_id`	string ou null	ID end-to-end do PIX
`requires_merchant_approval`	boolean	Se requer aprovação manual
`requires_compliance_review`	boolean	Se requer revisão de compliance
`bank_processing_status`	string	Status do processamento bancário (ver tabela abaixo)
`auto_approved`	boolean	Se foi auto-aprovado
`compliance_status`	string	Status de compliance (ver tabela abaixo)
`processed_at`	string (ISO 8601) ou null	Data/hora de processamento
`created_at`	string (ISO 8601)	Data/hora de criação

Status de Processamento Bancário

Status	Descrição
`pending`	Aguardando processamento bancário
`processing`	Em processamento no banco
`completed`	Processamento bancário concluído
`failed`	Falha no processamento bancário

Status de Compliance

Status	Descrição
`not_required`	Revisão de compliance não necessária
`pending`	Aguardando revisão de compliance
`under_review`	Em revisão de compliance
`approved`	Aprovado pela compliance
`rejected`	Rejeitado pela compliance

Erros Possíveis

404 Not Found

json

{
  "success": false,
  "message": "Saque não encontrado"
}

401 Unauthorized

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Fluxo de Status do Saque

O status do saque segue o fluxo abaixo, dependendo do parâmetro authorize:

Quando `authorize: true` (tentativa de auto-aprovação)

Sucesso: retorna processing → pode ir para paid ou failed
Falha: retorna failed (status final)

Quando `authorize: false` (aprovação manual)

Criação: retorna pending
Após aprovação: vai para processing ou failed
Processamento: processing → pode ir para paid ou failed

Status Finais

Apenas dois status são finais (não mudam mais):

paid - Saque concluído com sucesso
failed - Saque falhou (pode ter falhado em qualquer etapa)

Diagrama de Transições

authorize: true  → processing → paid ✓
                              → failed ✗

authorize: false → pending → processing → paid ✓
                          → failed ✗     → failed ✗

Idempotência

DICA

Use sempre um UUID v4 único para cada tentativa de saque. Se houver falha de rede, você pode reenviar a mesma requisição com a mesma Idempotency-Key sem risco de duplicação.

Veja mais detalhes em Idempotência.

Próximos Passos

Balance - Consultar saldo disponível
Idempotency - Entenda como funciona a idempotência

Saques (Withdrawals) ​

POST /v1/withdrawals ​

Headers ​

Request Body ​

Exemplo de Request ​

Response (201 Created) ​

Response (200 OK - Idempotente) ​

Campos da Resposta ​

Status do Saque ​

Erros Possíveis ​

Cenários de teste (payloads) ​

GET /v1/withdrawals/:id ​

Headers ​

Path Parameters ​

Exemplo de Request ​

Response (200 OK) ​

Campos da Resposta ​

Status de Processamento Bancário ​

Status de Compliance ​

Erros Possíveis ​

404 Not Found ​

401 Unauthorized ​

Fluxo de Status do Saque ​

Quando authorize: true (tentativa de auto-aprovação) ​

Quando authorize: false (aprovação manual) ​

Status Finais ​

Diagrama de Transições ​

Idempotência ​

Próximos Passos ​

Saques (Withdrawals)

POST /v1/withdrawals

Headers

Request Body

Exemplo de Request

Response (201 Created)

Response (200 OK - Idempotente)

Campos da Resposta

Status do Saque

Erros Possíveis

Cenários de teste (payloads)

GET /v1/withdrawals/:id

Headers

Path Parameters

Exemplo de Request

Response (200 OK)

Campos da Resposta

Status de Processamento Bancário

Status de Compliance

Erros Possíveis

404 Not Found

401 Unauthorized

Fluxo de Status do Saque

Quando `authorize: true` (tentativa de auto-aprovação)

Quando `authorize: false` (aprovação manual)

Status Finais

Diagrama de Transições

Idempotência

Próximos Passos