POST /v1/withdrawals

Solicita um saque via PIX (pix-out) do saldo disponível do vendedor.

Saques usam a base URL https://pix-out.aureacheckout.com.br, diferente da usada por transações. As credenciais são as mesmas. Ver Endpoint base.

O destino é sempre a chave PIX cadastrada na sua conta ÁureaPag. A requisição não aceita uma chave de destino — isso garante que uma credencial vazada não consiga desviar o saldo para terceiros. Para alterar o destino, atualize a chave PIX no painel.

Headers

Body (JSON)

Limite de frequência: é permitido um saque a cada 60 segundos por vendedor. Requisições dentro dessa janela são recusadas com 429, sem debitar o saldo. Isso protege contra requisições duplicadas — se o seu cliente sofrer um timeout e repetir a chamada, o saque não é criado duas vezes.

O amount é o valor bruto debitado do saldo. A taxa de saque configurada na sua conta é descontada dele, e o valor efetivamente transferido é o net_amount retornado na resposta.

Exemplo de request

{
  "amount": 25000
}

curl -X POST "https://pix-out.aureacheckout.com.br/v1/withdrawals" \
  -H "Authorization: Bearer SEU_TOKEN_40_CARACTERES" \
  -H "Content-Type: application/json" \
  -d '{"amount":25000}'

Resposta de sucesso (201 Created)

{
  "data": {
    "id": "8f3c1d2e-5a44-4b90-9e77-3c0b1a2d4e6f",
    "status": "created",
    "payment_method": "pix",
    "total_amount": 25000,
    "net_amount": 24500,
    "fixed_fee": 500,
    "created_at": "2026-09-06T14:02:11.421Z"
  }
}

Sobre o status inicial

O saque é criado com status created e o saldo é debitado imediatamente. O que acontece em seguida depende do modo de aprovação da sua conta:

• Aprovação automática: o PIX é disparado na mesma requisição e o saque segue para liquidação.
• Aprovação manual: o saque fica aguardando aprovação de um administrador da ÁureaPag antes de o PIX ser disparado.

Em ambos os casos a resposta é 201 com status: "created". Acompanhe a liquidação pelos webhooks.

Erros

400 Bad Request – Validação

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "amount": ["O valor mínimo de 'amount' é R$ 15,00. A quantia deve ser em centavos."]
    }
  }
}

Quando o corpo não é um JSON válido, o detail é uma string:

{
  "error": {
    "message": "Invalid request body.",
    "detail": "O corpo da requisição precisa ser um JSON válido."
  }
}

400 Bad Request – Chave PIX não cadastrada

{
  "error": {
    "message": "pix_key_not_configured",
    "detail": "Cadastre uma chave pix na sua conta antes de solicitar um saque via API."
  }
}

400 Bad Request – Saldo insuficiente

O valor solicitado excede o saldo disponível no momento do saque:

{
  "error": {
    "message": "withdrawal_not_created",
    "detail": "Saldo insuficiente para realizar o saque"
  }
}

401 Unauthorized

Token ausente ou inválido. Ver Autenticação.

403 Forbidden

Conta do vendedor não está ativa:

{
  "error": {
    "message": "account_status_blocked",
    "detail": "Não é possível realizar saques enquanto sua conta não estiver ativa"
  }
}

404 Not Found

Vendedor não encontrado para a credencial informada:

{
  "error": {
    "message": "seller_not_found",
    "detail": "Seller not found"
  }
}

429 Too Many Requests

Já houve um saque nos últimos 60 segundos:

{
  "error": {
    "message": "withdrawal_not_created",
    "detail": "Só é permitido um saque a cada 60 segundos. Tente novamente em 42 segundo(s)."
  }
}

Ou existe outro saque sendo processado neste exato momento para o mesmo vendedor:

{
  "error": {
    "message": "withdrawal_not_created",
    "detail": "Another withdrawal is in progress for this seller"
  }
}

Em nenhum dos dois casos o saldo é debitado. Aguarde o tempo indicado e repita a requisição.

500 Internal Server Error

Erro ao chamar o provedor bancário ou erro inesperado:

{
  "error": {
    "message": "Internal server error.",
    "detail": "Um erro inesperado ocorreu. Contate o suporte para mais informações."
  }
}