Enviar PIX

O envio de Pix para uma chave é feito com POST /v1/payouts.

Criar o envio

curl -X POST https://integrate.api.kyvopay.com.br/v1/payouts \
  -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_centavos": 25000,
    "pix_key": "destinatario@email.com",
    "pix_key_type": "email",
    "idempotency_key": "saque-1099"
  }'

pix_key_type aceita cpf, cnpj, email, phone e evp (chave aleatória).

A resposta traz o public_id, a taxa (fee_centavos), o líquido (net_centavos) e o status. Saldo insuficiente não é erro HTTP: a chamada volta 200 com status: "failed" e o motivo em failure_reason. Trate o status, não só o código HTTP.

Acompanhar

O status do saque pode demorar a fechar no provedor. Para atualizar, chame POST /v1/payouts/{payoutId}/sync e leia o status da resposta — e trate também os eventos payout.* do webhook.

Transferir para uma subconta

POST /v1/transfers não envia Pix: ele move saldo entre a sua empresa e uma subconta. Para pagar uma chave Pix, use o saque acima.