Produtos

Receber PIX

Crie cobranças PIX dinâmicas com QR Code. Quando o cliente paga, recebemos a confirmação do banco e disparamos um webhook pra você liberar o produto/serviço.

Fluxo completo

POST /v1/deposits → você recebe um QR Code (BR Code + imagem base64)
Mostra o QR pro cliente final (checkout, app, e-mail)
Cliente paga em qualquer banco brasileiro
Banco do cliente → BACEN → nosso provedor → API → seu webhook (deposit.paid)
Você libera o produto/serviço pro cliente

ⓘ

Tempo médio entre o pagamento e seu webhook: < 5 segundos. PIX é instantâneo.

Criar uma cobrança

curl -X POST https://api.realfy.io/v1/deposits \
  -H "X-Api-Key: realfy_live_..." \
  -H "X-Api-Secret: ..." \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "reference": "order-1234",
    "customer": {
      "name": "João Silva",
      "document": "12345678900",
      "email": "joao@email.com"
    },
    "metadata": { "orderId": "1234" }
  }'

const response = await fetch('https://api.realfy.io/v1/deposits', {
  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': `order-${orderId}`,
  },
  body: JSON.stringify({
    amount: 100.00,
    reference: `order-${orderId}`,
    customer: {
      name: customer.name,
      document: customer.cpf,
      email: customer.email,
    },
  }),
});

const { data } = await response.json();
// data.qrCode.payload → mostra o BR Code pro cliente pagar
// data.qrCode.imageEncoded → base64 da imagem QR pra renderizar
console.log(data.qrCode.payload);

import requests, os

response = requests.post(
    'https://api.realfy.io/v1/deposits',
    headers={
        'X-Api-Key': os.environ['REALFY_API_KEY'],
        'X-Api-Secret': os.environ['REALFY_API_SECRET'],
        'Content-Type': 'application/json',
        'Idempotency-Key': f'order-{order_id}',
    },
    json={
        'amount': 100.00,
        'reference': f'order-{order_id}',
        'customer': {
            'name': customer['name'],
            'document': customer['cpf'],
            'email': customer['email'],
        },
    },
)

data = response.json()['data']
print(data['qrCode']['payload'])  # BR Code pra mostrar pro cliente

Body

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor em reais (decimal, 2 casas)
`reference`	string	Sim	Identificador único da operação no seu sistema
`customer.name`	string	Sim	Nome do pagador
`customer.document`	string	Sim	CPF (11 dígitos) ou CNPJ (14)
`customer.email`	string	Sim	E-mail do pagador
`customer.phone`	string	Não	Telefone (E.164 ou DDD+número)
`metadata`	object	Não	Campos livres pra correlacionar no seu sistema
`expiration`	ISO8601	Não	Quando o QR expira. Default 24h.

Response (201)

{
  "success": true,
  "data": {
    "id": "dep_4054",
    "amount": 100.00,
    "feeAmount": 1.50,
    "netAmount": 98.50,
    "type": "deposit",
    "method": "pix",
    "currency": "brl",
    "status": "pending",
    "qrCode": {
      "payload": "00020126360014BR.GOV.BCB.PIX...",
      "imageEncoded": "iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "reference": "order-1234",
    "createdAt": "2026-05-26T13:30:00Z"
  }
}

✓

QR pronto pra usar

payload = código copia e cola (BR Code), funciona em qualquer banco.
imageEncoded = imagem QR em base64 pronta pra renderizar (<img src="data:image/png;base64,...">).

Consultar o status

GET https://api.realfy.io/v1/deposits/{id}
# ou
GET https://api.realfy.io/v1/deposits/reference/{sua-reference}

Status possíveis

Status	Significado
`pending`	QR criado, aguardando pagamento
`paid`	Pago — saldo já caiu na sua conta
`expired`	QR expirou sem pagamento (default 24h)
`failed`	Erro do provedor

Recomendado: webhook em vez de polling

Configure um webhook e não fique fazendo polling em GET /deposits/{id}. Pra cobranças volumosas, polling consome rate limit e gera latência. Webhook chega em < 5s.

⚠

Use Idempotency-Key

Toda cobrança nova deve enviar header Idempotency-Key. Se o request der timeout/falha, seu retry com a MESMA key não duplica a cobrança. Ver Idempotency.

Erros comuns

Code	O que aconteceu
`VALIDATION_ERROR`	Campo do body inválido (veja `details[]`)
`INVALID_DOCUMENT`	CPF/CNPJ com formato inválido
`DEPOSIT_LIMIT_EXCEEDED`	Valor acima do limite por transação
`DUPLICATE_REFERENCE`	Reference já usada — gere uma única