DOCS

Payouts

API de saques (Pix Out).

POST /v1/payouts

Cria um saque via Pix.

Request body (Pix chave)

CampoTipoObrigatórioDescrição
amountMoney✓Valor do saque
method"pix_chave"✓Método de saque
pix_keystring✓Chave Pix do destinatário
holder_namestringNome do titular
holder_documentstringCPF/CNPJ do titular — se enviado, precisa ser o da conta. A titularidade da chave é conferida no DICT (ver abaixo)
reasonstringMotivo/descrição
metadataobjectDados extras
source"pix" | "card"Saldo que paga o saque (padrão "pix"). Ver Saldo de origem

Request body (Pix dados bancários)

CampoTipoObrigatórioDescrição
amountMoney✓Valor do saque
method"pix_dados_bancarios"✓Método de saque
bank_codestring✓Código do banco (ISPB)
agencystring✓Agência
accountstring✓Conta
account_type"checking" | "savings"✓Tipo de conta
holder_namestring✓Nome do titular
holder_documentstring✓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_document enviado precisa ser esse mesmo documento, mas não "garante" a chave — quem decide é o DICT.
SituaçãoResposta
Chave de outro titular422 validation_error — "the Pix key does not belong to the account holder"
Chave inexistente no DICT422 validation_error
Chave mal formada (celular sem +55, por exemplo) ou pix_key_type que não bate422 validation_error
DICT indisponível503 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:

ModoDe onde sai
Só Woovi (padrão)Saldo Pix, pela Woovi, para a chave ou conta do pedido — como acima.
Só Pagar.meSaldo cartão na Pagar.me: transferência do seu recebedor para a conta bancária cadastrada nele.
AutomáticoO 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

HeaderDescrição
Idempotency-KeyChave ú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.

On this page