Depósitos PIX

Cria uma cobrança PIX dinâmica (QR Code) que seu cliente escaneia e paga no app do banco dele.

POST `/v1/pix/qrcode`

Headers

Header	Obrigatório	Descrição
`client-id`	sim	Sua chave pública
`client-secret`	sim	Sua chave secreta
`Idempotency-Key`	recomendado	Chave única por requisição — protege contra retry duplicado. Veja idempotência
`Content-Type`	sim	`application/json`

Body

{
  "amount": 9990,
  "payer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "joao@exemplo.com",
    "phone": "11999998888"
  },
  "external_id": "pedido-12345",
  "webhook_url": "https://seusite.com/webhooks/moneyfly",
  "utm": "instagram-ads",
  "expires_in": 3600
}

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	sim	Valor em CENTAVOS. Ex: `9990` = R$ 99,90. Mínimo 1 centavo, máximo R$ 1 bilhão
`payer`	object	não	Dados do pagador. Todos os campos internos também são opcionais. Use o que tiver no seu fluxo de checkout
`payer.name`	string	não	Nome completo do pagador (2–200 chars)
`payer.document`	string	não	CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita formatado ou só números
`payer.email`	string	não	Email válido, max 254 chars
`payer.phone`	string	não	DDD + número, 10 ou 11 dígitos
`external_id`	string	não	Seu ID interno. Aparece nos webhooks pra facilitar conciliação
`webhook_url`	string	não	URL específica pra notificar esta transação (override do webhook global)
`utm`	string	não	Tag de rastreamento (max 200 chars)
`expires_in`	integer	não	Segundos até expirar. Padrão 3600 (1h). Mínimo 60, máximo 86400 (24h)

Resposta (HTTP 201)

{
  "internal_id": "cl_abc123xyz...",
  "external_id": "pedido-12345",
  "status": "pending",
  "amount": 9990,
  "fee_amount": 198,
  "net_amount": 9792,
  "qrcode": "00020126580014br.gov.bcb.pix...",
  "qr_image_url": "/v1/pix/qrcode/cl_abc123/image",
  "expires_at": "2026-04-24T19:00:00Z",
  "created_at": "2026-04-24T18:00:00Z"
}

Campo	Descrição
`internal_id`	ID gerado pelo Moneyfly. Guarde pra consultar depois
`external_id`	O mesmo que você passou no body (ou null)
`status`	Inicialmente sempre `"pending"`
`amount`	Valor bruto em centavos
`fee_amount`	Taxa Moneyfly em centavos
`net_amount`	Líquido (= amount - fee_amount) que vai pro seu saldo quando for pago
`qrcode`	String PIX copia-e-cola (EMV padrão BACEN)
`qr_image_url`	URL opcional que renderiza a imagem PNG do QR Code
`expires_at`	Quando o QR deixa de aceitar pagamento

Fluxo completo

curl -X POST https://api.moneyflybr.com/v1/pix/qrcode \
  -H "client-id: mf_pk_live_AbCd..." \
  -H "client-secret: mf_sk_live_XyZ..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9990,
    "external_id": "pedido-12345"
  }'

1. Você mostra o QR

No seu app/site, renderiza a string qrcode como QR Code visual (qualquer lib JS faz — qrcode.react, qrcode.js, etc.) OU só mostra ela como texto "copia-e-cola".

2. Cliente paga no banco

O cliente abre o app do banco dele, escaneia ou cola, confirma. O banco dele envia o PIX pro SPI.

3. Moneyfly notifica seu webhook

Em 1-2 segundos, o Moneyfly dispara um POST no webhook_url configurado:

{
  "event": "deposit.paid",
  "event_id": "evt_xxx",
  "internal_id": "cl_abc123xyz...",
  "external_id": "pedido-12345",
  "status": "paid",
  "amount_cents": 9990,
  "timestamp": "2026-04-24T18:01:32Z",
  "attempt": 1
}

Veja como validar e processar em webhooks.

Valores mínimos e máximos

Mínimo: R$ 0,01 (1 centavo)
Máximo: R$ 1.000.000.000 (1 bilhão)

Erros comuns

Status	Código	Quando acontece
422	Unprocessable Entity	Schema inválido (valor zero, email ruim, CPF inválido)
401	Unauthorized	`client-id` ou secret inválido
403	Forbidden	Conta KYC pendente ou suspensa
409	Conflict	`Idempotency-Key` reutilizada pra operação diferente

Catálogo completo em códigos de erro.

Depósitos (Cash-in)