Saques PIX

Envia um PIX do seu saldo Moneyfly pra qualquer chave PIX (CPF, CNPJ, email, telefone ou aleatória).

POST `/v1/pix/payout`

Headers

Header	Obrigatório
`client-id`	sim
`client-secret`	sim
`Idempotency-Key`	recomendado
`Content-Type`	sim

Body

{
  "amount": 5000,
  "pix_key_type": "email",
  "pix_key": "beneficiario@exemplo.com",
  "beneficiary": {
    "name": "Maria Teste",
    "document": "98765432100"
  },
  "external_id": "saque-001",
  "webhook_url": "https://seusite.com/webhooks/moneyfly"
}

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	sim	Valor em centavos a enviar. Min 100, max R$ 100.000
`pix_key_type`	enum	sim	`cpf`, `cnpj`, `email`, `phone` ou `random`
`pix_key`	string	sim	A chave em si
`beneficiary.name`	string	sim	Nome completo do beneficiário
`beneficiary.document`	string	sim	CPF ou CNPJ do beneficiário
`external_id`	string	não	Seu ID interno
`webhook_url`	string	não	URL específica pra notificar

Resposta (HTTP 201)

{
  "internal_id": "cl_def456...",
  "external_id": "saque-001",
  "status": "pending",
  "amount": 5000,
  "fee_amount": 0,
  "total_debited": 5000,
  "provider_e2e_id": "E12345678202604241830ABCD...",
  "created_at": "2026-04-24T18:30:00Z"
}

Campo	Descrição
`amount`	Valor que o beneficiário recebe
`fee_amount`	Taxa Moneyfly (padrão 0 em saque)
`total_debited`	`amount + fee_amount` — total deduzido do seu saldo
`provider_e2e_id`	endToEndId do PIX no SPI/BACEN. Rastreável oficialmente

Tipos de chave PIX

Tipo	Formato	Exemplo
`cpf`	11 dígitos	`12345678909`
`cnpj`	14 dígitos	`12345678000190`
`email`	email válido	`fulano@email.com`
`phone`	DDD + número (10-11 dígitos)	`11988887777`
`random`	UUID da chave aleatória	`123e4567-e89b-12d3-a456-426614174000`

Política de taxa

Taxa é ADICIONADA por cima — não deduzida do valor enviado. Se você pede saque de R$ 50 e sua taxa é R$ 2:

Beneficiário recebe R$ 50 exatos
Seu saldo é debitado R$ 52 (total_debited)

Essa é a prática usada por gateways sérios porque dá controle total sobre quanto chega — merchant não precisa calcular "quanto a mais pedir pra líquido ser X".

Saldo insuficiente

Se seu saldo disponível for menor que amount + fee, a API responde 400 com detalhes:

{
  "error": "Insufficient Balance",
  "message": "Saldo insuficiente pra realizar o saque.",
  "available_cents": 3000,
  "required_cents": 5200
}

Veja seu saldo disponível em Conta → Saldo antes de pedir.

Status do saque

Depois do 201 Created retornado:

pending: PIX em processamento no SPI
paid: PIX efetivado, dinheiro chegou no beneficiário (webhook payout.paid disparado)
cancelled: cancelado pela provedora (webhook payout.cancelled, saldo devolvido)
failed: falha no SPI (webhook payout.failed, saldo devolvido)

A informação final vem pelo webhook. Em falha/cancelamento, o saldo inteiro (inclui taxa) é devolvido — taxa só é cobrada em saque confirmado.

Saques (Cash-out)