Payouts
API de saques (Pix Out).
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 — se enviado, precisa ser o da conta. A titularidade da chave é conferida no DICT (ver abaixo) | |
reason | string | Motivo/descrição | |
metadata | object | Dados extras | |
source | "pix" | "card" | Saldo que paga o saque (padrão "pix"). Ver Saldo de origem |
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 |
source | "pix" | "card" | Saldo que paga o saque (padrão "pix") |
Titularidade da chave Pix (DICT)
Todo saque vai só para uma conta do mesmo titular da sua conta (o CPF/CNPJ do
cadastro; numa subconta de mesmo documento, o da conta-mãe). Para pix_chave,
a chave é consultada no DICT antes de qualquer valor ser reservado:
- chave CPF/CNPJ: precisa ser o próprio documento da conta;
- chave e-mail, celular ou aleatória: o titular que o DICT informa precisa ser
o documento da conta. Um
holder_documentenviado precisa ser esse mesmo documento, mas não "garante" a chave — quem decide é o DICT.
| Situação | Resposta |
|---|---|
| Chave de outro titular | 422 validation_error — "the Pix key does not belong to the account holder" |
| Chave inexistente no DICT | 422 validation_error |
Chave mal formada (celular sem +55, por exemplo) ou pix_key_type que não bate | 422 validation_error |
| DICT indisponível | 503 vendor_unavailable — nada foi reservado; tente de novo |
A chave é conferida de novo no DICT no momento do envio (depois da aprovação):
se ela tiver mudado de titular nesse meio-tempo, o saque falha, o valor volta
ao saldo e o evento payout.failed é enviado. O Pix sai amarrado à conta que o
DICT acabou de informar.
Saque por pix_dados_bancarios não tem consulta ao DICT (ele só existe para
chaves): holder_document precisa ser o documento da conta, a conta é validada
na Transfeera e o CPF/CNPJ do titular segue no Pix, para o banco recebedor
recusar uma divergência.
Saldo de origem
O saldo disponível é separado em saldo Pix e saldo cartão (ver
Balance). source escolhe de qual deles o saque sai; o
saque em si é sempre enviado por Pix. Sem source, o saque sai do saldo Pix,
como antes.
O valor precisa caber em withdrawable_pix (ou withdrawable_card) de
GET /v1/balance. O outro saldo nunca completa a diferença: sem saldo
suficiente na origem escolhida, a resposta é 409 e a mensagem diz qual saldo
faltou (saldo Pix ou saldo cartão).
Se o saque falhar ou for negado, o valor volta para o mesmo saldo de onde saiu.
Os eventos payout.succeeded e payout.failed trazem source em data.
Origem escolhida pela Kirvex
Quando a conta tem o saque automático ligado, a equipe Kirvex pode definir de
onde sai o saque pedido sem source:
| Modo | De onde sai |
|---|---|
| Só Woovi (padrão) | Saldo Pix, pela Woovi, para a chave ou conta do pedido — como acima. |
| Só Pagar.me | Saldo cartão na Pagar.me: transferência do seu recebedor para a conta bancária cadastrada nele. |
| Automático | O saldo da adquirente por onde você mais vendeu nos últimos 5 dias; sem saldo nela, o próximo. |
Na Pagar.me o destino é sempre a conta bancária do recebedor, nunca a chave
Pix ou a conta enviada no pedido. A resposta traz "method": "pagarme_transfer",
"vendor": "pagarme" e o destino em destination (banco, agência, os quatro
últimos dígitos da conta e o titular). A taxa de transferência da Pagar.me sai
do valor.
Um saque sai de uma origem só. No modo automático, se nenhum saldo sozinho
cobre o valor, a resposta é 409 com o quanto há em cada um. Se o seu saldo
cobre mas a conta da adquirente não tem o valor naquele momento, o saque é
criado e aguarda a aprovação da equipe (awaiting_approval).
Quando a Kirvex escolhe a origem, a resposta traz routing:
"routing": { "mode": "auto", "reason": "auto: card balance at Pagar.me, most sold in the last 5 days" }
Mandar source no pedido continua escolhendo a origem como sempre.
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",
"source": "pix",
"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.