Começar

API Realfy

Infraestrutura PIX completa. Receba e envie pagamentos em uma única integração REST. 5 minutos do curl até a primeira cobrança paga.

1. Crie sua conta

Acesse realfy.io/signup e crie sua empresa. Depois, no painel, vá em API Keys e gere um par key + secret.

⚠

Guarde o secret

O X-Api-Secret é mostrado UMA vez na criação. Guarde num gerenciador de credenciais. Se perder, gere uma nova key — você pode ter várias ativas ao mesmo tempo.

2. Faça sua primeira request

Vamos criar uma cobrança PIX de R$ 50. O exemplo abaixo gera um QR Code (BR Code) que pode ser pago por qualquer banco brasileiro.

curl -X POST https://api.realfy.io/v1/deposits \
  -H "X-Api-Key: rfy_live_..." \
  -H "X-Api-Secret: ..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{
    "amount": 50.00,
    "reference": "order-001"
  }'

// npm i node-fetch (ou use fetch nativo do Node 18+)
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: 50.00,
    reference: `order-${orderId}`,
  }),
});

const { data } = await response.json();
console.log(data.qrCode.payload); // BR Code pra pagar

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': 50.00,
        'reference': f'order-{order_id}',
    },
)

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

<?php
$response = file_get_contents('https://api.realfy.io/v1/deposits', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => implode("\r\n", [
            'X-Api-Key: ' . getenv('REALFY_API_KEY'),
            'X-Api-Secret: ' . getenv('REALFY_API_SECRET'),
            'Content-Type: application/json',
            'Idempotency-Key: order-' . $orderId,
        ]),
        'content' => json_encode([
            'amount' => 50.00,
            'reference' => 'order-' . $orderId,
        ]),
    ],
]));

$data = json_decode($response, true)['data'];
echo $data['qrCode']['payload']; // BR Code pra pagar

Resposta esperada:

{
  "success": true,
  "data": {
    "id": "dep_4054",
    "amount": 50.00,
    "feeAmount": 0.75,
    "netAmount": 49.25,
    "status": "pending",
    "qrCode": {
      "payload": "00020126360014BR.GOV.BCB.PIX...",
      "imageEncoded": "iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "reference": "order-001",
    "createdAt": "2026-05-26T13:30:00Z"
  }
}

3. Receba o webhook quando for pago

Quando o cliente paga o QR Code, enviamos um POST pro endpoint que você cadastrou:

POST https://seu-site.com/webhooks/realfy
Content-Type: application/json
X-Realfy-Signature: t=1779800000,v1=<hmac-sha256>
X-Realfy-Event: deposit.paid
X-Realfy-Delivery-Id: del_xyz

{
  "event": "deposit.paid",
  "data": {
    "id": "dep_4054",
    "amount": 50.00,
    "status": "paid",
    "reference": "order-001"
  }
}

Você deve verificar a assinatura antes de processar o evento. Veja como em Webhooks.

4. Próximos passos

API Reference completa — todos endpoints, parâmetros, exemplos
Idempotency — como fazer retries com segurança
Webhooks — verificar assinatura, retry, deliveries
Rate Limits — quotas por endpoint
Erros — catálogo de codes e o que fazer

ⓘ

Precisa de ajuda? Manda mensagem pra hiago@realfy.io — tempo de resposta médio: 2 horas em dia útil.