Payouts

POST /v1/payouts

Cria um saque via Pix.

Request body (Pix chave)

Campo	Tipo	Obrigatório	Descrição
amount	Money	✓	Valor do saque
method	"pix_chave"	✓	Método de saque
pix_key	string	✓	Chave Pix do destinatário
holder_name	string		Nome do titular
holder_document	string		CPF/CNPJ do titular
reason	string		Motivo/descrição
metadata	object		Dados extras

Request body (Pix dados bancários)

Campo	Tipo	Obrigatório	Descrição
amount	Money	✓	Valor do saque
method	"pix_dados_bancarios"	✓	Método de saque
bank_code	string	✓	Código do banco (ISPB)
agency	string	✓	Agência
account	string	✓	Conta
account_type	"checking" | "savings"	✓	Tipo de conta
holder_name	string	✓	Nome do titular
holder_document	string	✓	CPF/CNPJ

Headers obrigatórios

Header	Descrição
Idempotency-Key	Chave única para evitar saques duplicados

Modo de teste

Saque só existe com dinheiro real: uma chave sk_test_ recebe 422 test_mode_unavailable e nada é criado. Use uma chave sk_live_.

Exemplo

curl -X POST https://api.kirvex.com.br/v1/payouts \
  -u sk_live_...: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-mensal-abril" \
  -d '{
    "amount": { "amount": "100000", "currency": "BRL" },
    "method": "pix_chave",
    "pix_key": "joao@example.com"
  }'

Resposta (201)

{
  "id": "py_01J...",
  "object": "payout",
  "status": "pending",
  "method": "pix_chave",
  "amount": { "amount": "100000", "currency": "BRL" },
  "vendor": "woovi",
  "vendor_ref": null,
  "reason": null,
  "created_at": "2026-04-29T12:00:00Z",
  "succeeded_at": null,
  "failed_at": null,
  "failure_reason": null
}

---

GET /v1/payouts/:id

Retorna um saque pelo ID.

---

GET /v1/payouts

Lista saques com paginação por cursor.