Produtos

Enviar PIX

Transferências PIX pra qualquer chave (CPF, CNPJ, e-mail, telefone, EVP). Validação DICT automática, saldo é debitado da sua conta, e webhook avisa quando entrega ou falha.

Fluxo completo

POST /v1/withdrawals com valor + chave PIX
Sistema valida saldo, limites e taxa
Saldo é reservado imediatamente (status pending)
Worker manda pro provedor BaaS (status processing)
BACEN processa e responde (geralmente em segundos)
Webhook withdrawal.completed OU withdrawal.failed chega no seu sistema
Se falhou: saldo é estornado automaticamente

⚠

Saldo necessário

Antes de chamar a API, seu saldo BRL precisa ser maior que amount + feeAmount. Veja GET /v1/balances.

Enviar uma transferência

curl -X POST https://api.realfy.io/v1/withdrawals \
  -H "X-Api-Key: realfy_live_..." \
  -H "X-Api-Secret: ..." \
  -H "Idempotency-Key: payout-9182" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "pixKey": "joao@email.com",
    "pixKeyType": "email",
    "reference": "payout-9182",
    "metadata": { "description": "Pagamento referente a serviço #4521" }
  }'

const response = await fetch('https://api.realfy.io/v1/withdrawals', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.REALFY_API_KEY,
    'X-Api-Secret': process.env.REALFY_API_SECRET,
    'Content-Type': 'application/json',
    'Idempotency-Key': `payout-${payoutId}`,
  },
  body: JSON.stringify({
    amount: 250.00,
    pixKey: 'joao@email.com',
    pixKeyType: 'email',
    reference: `payout-${payoutId}`,
  }),
});

const { data } = await response.json();
// data.status: "processing" — escuta o webhook withdrawal.completed
// ou withdrawal.failed pra saber o desfecho

import requests, os

response = requests.post(
    'https://api.realfy.io/v1/withdrawals',
    headers={
        'X-Api-Key': os.environ['REALFY_API_KEY'],
        'X-Api-Secret': os.environ['REALFY_API_SECRET'],
        'Content-Type': 'application/json',
        'Idempotency-Key': f'payout-{payout_id}',
    },
    json={
        'amount': 250.00,
        'pixKey': 'joao@email.com',
        'pixKeyType': 'email',
        'reference': f'payout-{payout_id}',
    },
)

data = response.json()['data']
print(data['status'])  # 'processing' — aguarda webhook

Body

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor em reais (decimal, 2 casas)
`pixKey`	string	Sim	Chave PIX do destinatário
`pixKeyType`	enum	Sim	`cpf` · `cnpj` · `email` · `phone` · `evp`
`reference`	string	Sim	Identificador único da operação
`customer`	object	Não	Dados do destinatário (opcional — DICT resolve)
`metadata`	object	Não	Campos livres + `description` opcional (até 140 chars)

Formato das chaves PIX

Tipo	Formato aceito	Exemplo
`cpf`	11 dígitos (com ou sem formatação)	`12345678900`
`cnpj`	14 dígitos	`12345678000100`
`email`	RFC 5322	`joao@email.com`
`phone`	E.164 (preferível) ou DDD+número	`+5562999999999`
`evp`	UUID v4	`abc-def-...-uuid`

ⓘ

Normalização automática

Você pode mandar com formato (ex: (62) 99999-9999) — o backend normaliza pro padrão do DICT antes de chamar o provedor. CPF, telefone, email — tudo limpo automaticamente.

Response (201)

{
  "success": true,
  "data": {
    "id": "wth_8255",
    "amount": 250.00,
    "feeAmount": 3.00,
    "totalAmount": 253.00,
    "type": "withdrawal",
    "method": "pix",
    "currency": "brl",
    "status": "processing",
    "pixKey": "joao@email.com",
    "reference": "payout-9182",
    "createdAt": "2026-05-26T14:00:00Z"
  }
}

Status possíveis

Status	Significado	Próximo passo
`pending`	Reservado, na fila pro provedor	Aguardar
`processing`	Provedor BaaS processando junto ao BACEN	Aguardar webhook
`completed`	PIX entregue no destinatário	Operação concluída
`failed`	Falha do BACEN/provedor	Saldo estornado automaticamente

Comprovante PDF

GET https://api.realfy.io/v1/withdrawals/{id}/receipt

Retorna PDF com chave PIX, valor, end-to-end ID, ISPB do banco do destinatário, data, etc. Útil pra anexar em e-mail de confirmação pro cliente final.

Cuidado: PIX é instantâneo e irreversível

Diferente de cartão, não tem chargeback. Uma vez completed, só dá pra recuperar via estorno solicitado e aceito pelo destinatário. Valide bem antes de enviar.

IP allowlist (recomendado)

No painel da sua API key, configure os IPs autorizados a fazer cash-out. Se a request vier de fora da lista, retorna 403 IP_NOT_ALLOWED. Veja Autenticação.

Erros comuns

Code	HTTP	O que aconteceu
`INSUFFICIENT_BALANCE`	400	Saldo não cobre valor + taxa
`WITHDRAWAL_LIMIT_EXCEEDED`	400	Acima do limite por transação
`PIX_KEY_NOT_FOUND`	422	Chave não existe no DICT do BACEN
`IP_NOT_ALLOWED`	403	IP fora da allowlist configurada
`DUPLICATE_REFERENCE`	409	Reference já usada
`IDEMPOTENCY_KEY_CONFLICT`	409	Idempotency-Key reusada com body diferente

Boas práticas

Sempre use Idempotency-Key — em retry, evita PIX duplicado
Configure IP allowlist — bloqueia cash-out se sua API key vazar
Use webhooks, não polling — confirmação chega em segundos
Logue o requestId de cada response pra debug com suporte
Trate failed — não é o fim do mundo, saldo volta. Apenas notifique o usuário e dê opção de retry