Saque PIX

Cria uma solicitação de saque PIX. O comportamento esperado é assíncrono: a resposta inicial normalmente retorna PROCESSING e o status final chega depois via webhook na URL informada em clientCallbackUrl.

Endpoint: POST /api/withdrawals/withdraw

Alias compatível: /api/payments/withdrawal

PIX copia e cola

Para pagamento via payload EMV (copia-e-cola), use o endpoint POST /api/payments/pix-copy-paste/pay. O sistema aplica taxa de saque no momento da requisição.

Autenticação

Use Authorization: Bearer SEU_JWT.
O token é obtido em POST /api/auth/login.

Parâmetro	Tipo	Descrição
amount *	number	Valor do saque.
external_id *	string	ID único no seu sistema.
pix_key *	string	Chave PIX do destinatário.
key_type *	string	CPF, EMAIL, PHONE.
clientCallbackUrl *	string	URL para notificação de status.
description	string	Descrição do saque.
gateway	string	Gateway opcional para roteamento.

curl -X POST 'https://api.pulsepag.com/api/withdrawals/withdraw' \
  --header 'Authorization: Bearer SEU_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 25,
    "external_id": "saque-001",
    "pix_key": "cliente@email.com",
    "key_type": "EMAIL",
    "description": "Saque do usuário",
    "clientCallbackUrl": "https://seusistema.com/webhooks/withdraw"
  }'

{
  "message": "Withdrawal processed successfully.",
  "transactionId": "54345",
  "withdrawal": {
    "transaction_id": "54345",
    "external_id": "saque-001",
    "status": "PROCESSING",
    "amount": 25,
    "fee": 1.25,
    "total": 26.25,
    "type": "Withdrawal"
  }
}

Callback

O webhook final é enviado para clientCallbackUrl.
Webhooks externos podem ser assinados com X-PulsePag-Webhook-Timestamp e X-PulsePag-Webhook-Signature.
Trate PROCESSING como status normal de aceite inicial.