Saques (payouts)

Envie dinheiro para fora da sua carteira PagNow via PIX, TED ou cripto.

Criar um saque

POST /v1/withdrawals

curl -X POST 'https://v2.pagnow.com/v1/withdrawals' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "type": "PIX",
    "amount": 10000,
    "currency": "BRL",
    "pixKey": "maria@exemplo.com",
    "pixKeyType": "EMAIL"
  }'

amount é em centavos. Para cripto, envie type: "CRYPTO" com cryptoAddress, cryptoNetwork e cryptoCurrency.

Exemplo — saque em cripto (USDT/BSC)

curl -X POST 'https://v2.pagnow.com/v1/withdrawals' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "type": "CRYPTO",
    "amount": 5000,
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "BSC",
    "cryptoAddress": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c",
    "idempotencyKey": "payout-usdt-001"
  }'

amount continua em centavos de USDT (2 casas) — 5000 = 50,00 USDT.

Você pode ter várias carteiras na mesma moeda (ver Carteiras). Omita walletId e o saque usa a carteira padrão da moeda (ou qualquer gastável com saldo); informe walletId para debitar uma carteira específica.

Exemplo — saque via Binance Pay (USDT para uma conta Binance)

Se o destinatário tem conta na Binance, use type: "BINANCE_PAY" — a transferência chega na hora, direto no saldo Binance dele, sem taxa de rede e sem risco de erro de endereço on-chain. Informe o Binance ID (numérico, no perfil da conta) ou o email da conta Binance:

curl -X POST 'https://v2.pagnow.com/v1/withdrawals' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "type": "BINANCE_PAY",
    "amount": 5000,
    "currency": "USDT",
    "binanceId": "349183884",
    "idempotencyKey": "payout-binance-001"
  }'

Para carteira externa (endereço 0x…), use type: "CRYPTO" (acima). Regra prática: Binance ID/email → BINANCE_PAY; endereço on-chain → CRYPTO.

Campos

Cotar um saque (taxa)

POST /v1/withdrawals/quote — calcula a taxa e o gross-up para o destinatário receber exatamente o valor desejado, antes de criar o saque.

curl -X POST 'https://v2.pagnow.com/v1/withdrawals/quote' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{ "value": 10000, "currency": "BRL" }'

value é em centavos. A resposta traz a taxa e o valor total a ser debitado da carteira para que o destinatário receba o value cheio.

Validar chave PIX antes de sacar

POST /v1/withdrawals/validate-pix-key — consulta se uma chave PIX existe e retorna os dados do titular antes de criar o saque.

curl -X POST 'https://v2.pagnow.com/v1/withdrawals/validate-pix-key' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{ "pixKey": "maria@exemplo.com", "pixKeyType": "EMAIL" }'

Aprovação automática vs manual

Todo saque começa em PENDING. Se ele é despachado na hora ou fica aguardando aprovação manual depende da configuração de saque automático da sua conta:

• Saque automático ativado — o saque é aprovado e enviado imediatamente.
• Saque automático desativado (padrão) — o saque fica PENDING até a PagNow aprovar.

Fale com seu gerente de conta para ativar o saque automático.

Consultar e listar

# Um saque específico
curl 'https://v2.pagnow.com/v1/withdrawals/{id}' \
  -H 'apikey: pnk_sua_chave_aqui'

# Listar com paginação; filtra por status
curl 'https://v2.pagnow.com/v1/withdrawals?page=1&limit=20&status=PENDING' \
  -H 'apikey: pnk_sua_chave_aqui'

Parâmetros de listagem: page, limit, status.

Ciclo de vida do saque

PENDING → APPROVED → PROCESSING → CONFIRMING → COMPLETED
                               → FAILED
PENDING → CANCELLED
PENDING → REJECTED

O ciclo de vida chega pelos eventos de webhook withdrawal.*. Um saque que falha após o débito tem o valor estornado para a carteira automaticamente.