Saldo e saques (cash out)

Consulte o saldo da conta e envie dinheiro por PIX para uma chave, direto pela API.

Valores de saldo e saque são em reais (250.00), diferente das cobranças, que usam centavos.

Consultar o saldo

GET/@seller/withdraw/balanceChave de API · permissão balance:read

Consulta

curl "https://api.apix.tec.br/@seller/withdraw/balance" \
  -H "X-API-Key: pk_live_a1b2c3d4..."

Resposta 200

{
  "hasError": false,
  "data": {
    "total_balance": 1520.40,
    "available_balance": 980.10,
    "reserve_amount": 140.30,
    "pending_balance": 400.00,
    "pending_withdrawals": 0,
    "approved_withdrawals": 2300.00
  }
}

Campo	O que é
total_balance	Tudo que entrou, menos o que saiu
available_balance	O que dá para sacar agora
pending_balance	Vendas ainda no prazo de liberação
reserve_amount	Reserva de segurança retida
pending_withdrawals	Saques pedidos e ainda não concluídos
approved_withdrawals	Total já pago em saques

Pedir um saque

POST/@seller/withdrawChave de API · permissão withdraw:create

net_amount é quanto o destinatário recebe. As taxas entram por cima, então o valor debitado do saldo (gross_amount) é maior.

Campo	Tipo	Obrigatório	Descrição
pix_key	string	Sim	Chave PIX de destino
net_amount	number	Sim	Valor líquido a receber, em reais
pix_type	string	Não	CPF, CNPJ, EMAIL, PHONE ou RANDOM; deduzido da chave quando omitido
recipient_document	string	Não	CPF/CNPJ do titular da chave; alguns provedores recusam se não bater
recipient_document_type	string	Não	CPF ou CNPJ; deduzido pelo tamanho do documento
recipient_name	string	Não	Nome do titular da chave

Saque

curl -X POST "https://api.apix.tec.br/@seller/withdraw" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_a1b2c3d4..." \
  -d '{
    "pix_key": "12345678901",
    "net_amount": 250.00,
    "pix_type": "CPF",
    "recipient_document": "12345678901",
    "recipient_document_type": "CPF",
    "recipient_name": "João da Silva"
  }'

Resposta 200

{
  "hasError": false,
  "message": "Saque enviado ao provedor com sucesso",
  "data": {
    "withdraw_id": "8b1f7a3e-2c4d-4e5f-9a6b-7c8d9e0f1a2b",
    "status": "processing",
    "gross_amount": 253.50,
    "platform_fee": 3.00,
    "provider_fee": 0.50,
    "net_amount": 250.00,
    "external_withdraw_id": "id-no-provedor",
    "message": "Saque enviado ao provedor com sucesso"
  }
}

A resposta sai com status processing: o PIX foi enviado ao provedor. A confirmação vem depois — consulte o saque para saber o desfecho.

Consultar um saque

GET/@seller/withdraw/{withdraw_id}Chave de API · permissão withdraw:create

Status	Significado
pending	Saque criado, aguardando aprovação
approved	Aprovado — o PIX foi enviado e confirmado
processing	Enviado ao provedor, aguardando confirmação
gateway_error	O provedor recusou o envio; veja gateway_error_message
refused	Recusado na análise

Proteções contra saque duplicado

Situação	Resposta
Outro saque da mesma conta ainda em processamento	409 · Já existe um saque em processamento para esta conta
Mesma chave e valor repetidos em seguida	409 · Saque duplicado detectado
Chave PIX fora da lista autorizada na API key	403 · Esta chave PIX não está autorizada para esta API key
Saldo insuficiente	400
Mais de 5 pedidos por minuto	429

Em caso de timeout, não repita o pedido às cegas: consulte o saque pelo withdraw_id ou o saldo antes de tentar de novo.