Docs
Status Site Dashboard
Início Rápido

Integre Pix em minutos.

Uma API. Todos os pagamentos. Gere cobranças Pix com QR Code dinâmico, configure webhooks em tempo real e divida receitas automaticamente — sem mensalidade.

Ambiente único. A HarpyPay opera com um único endpoint de produção. Não há ambiente sandbox separado — use valores baixos (R$ 1,00) para testes iniciais.

1. Autentique-se

Toda requisição deve incluir seu API Key no header X-API-KEY. Encontre sua chave em Dashboard → Configurações → API & Integrações.

curl -X POST https://harpypay.com/api/v1/depositar \
  -H "X-API-KEY: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 100.00,
    "nome": "João Silva",
    "cpf": "11370243480"
  }'
$response = file_get_contents('https://harpypay.com/api/v1/depositar', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "X-API-KEY: sua_api_key_aqui\r\nContent-Type: application/json\r\n",
        'content' => json_encode([
            'valor' => 100.00,
            'nome'  => 'João Silva',
            'cpf'   => '11370243480'
        ])
    ]
]));
$data = json_decode($response, true);
const resp = await fetch('https://harpypay.com/api/v1/depositar', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'sua_api_key_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    valor: 100.00,
    nome: 'João Silva',
    cpf: '11370243480'
  })
});
const data = await resp.json();
import httpx

resp = httpx.post(
    "https://harpypay.com/api/v1/depositar",
    headers={"X-API-KEY": "sua_api_key_aqui"},
    json={
        "valor": 100.00,
        "nome": "João Silva",
        "cpf": "11370243480"
    }
)
data = resp.json()

2. Gerar Cobrança Pix (Cash-in)

POST /api/v1/depositar Requer autenticação
Cria uma cobrança Pix dinâmica e retorna o QR Code Base64, a string Pix Copia e Cola e o ID do pagamento para polling ou webhook.

Parâmetros do body (JSON)

Campo Tipo Obrig. Descrição
valor float Sim Valor da cobrança em BRL. Mínimo: R$ 10,00. Máximo: R$ 5.000,00.
nome string Sim Nome completo do pagador (obrigatório para compliance e antifraude). Mínimo de 3 caracteres.
cpf string Sim CPF (11 dígitos) ou CNPJ (14 dígitos) válido do pagador. Obrigatório para validação junto ao BACEN e checagem MED.
email string Opcional E-mail do pagador para envio automático de recibo de confirmação.
telefone string Opcional Celular do pagador (com DDD). Ativa notificação de confirmação via WhatsApp.
split_rules array Opcional Array de regras de divisão de receita. Veja Split de Receita.
curl -X POST https://harpypay.com/api/v1/depositar \
  -H "X-API-KEY: sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 149.90,
    "nome": "João Silva",
    "cpf": "11370243480",
    "email": "[email protected]",
    "telefone": "11987654321"
  }'
$payload = json_encode([
    'valor'    => 149.90,
    'nome'     => 'João Silva',
    'cpf'      => '11370243480',
    'email'    => '[email protected]',
    'telefone' => '11987654321',
]);

$opts = ['http' => [
    'method'  => 'POST',
    'header'  => "X-API-KEY: sk_live_abc123xyz789\r\nContent-Type: application/json\r\n",
    'content' => $payload,
]];

$response = file_get_contents(
    'https://harpypay.com/api/v1/depositar',
    false,
    stream_context_create($opts)
);

$data = json_decode($response, true);
$pix  = $data['pix_copia_cola'];      // string Pix Copia e Cola
$qr   = $data['qrcode_base64'];       // imagem QR em base64
$id   = $data['pagamento_id'];         // ID para verificação
const resp = await fetch('https://harpypay.com/api/v1/depositar', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'sk_live_abc123xyz789',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    valor: 149.90,
    nome: 'João Silva',
    cpf: '11370243480',
    email: '[email protected]',
    telefone: '11987654321'
  })
});

const data = await resp.json();

console.log(data.pagamento_id);    // Para verificar status
console.log(data.pix_copia_cola);  // String Pix Copia e Cola
console.log(data.qrcode_base64);   // QR Code em base64
import httpx

resp = httpx.post(
    "https://harpypay.com/api/v1/depositar",
    headers={"X-API-KEY": "sk_live_abc123xyz789"},
    json={
        "valor": 149.90,
        "nome": "João Silva",
        "cpf": "11370243480",
        "email": "[email protected]",
        "telefone": "11987654321",
    }
)

data = resp.json()
print(data["pagamento_id"])    # ID da cobrança
print(data["pix_copia_cola"])  # String Pix
print(data["qrcode_base64"])   # QR Code Base64

Resposta de Sucesso (200 OK)

{
  "status": "sucesso",
  "pagamento_id": "pix_live_83921048ab4c",
  "valor": 149.90,
  "pix_copia_cola": "00020101021226640014br.gov.bcb.pix...",
  "pix_copia_e_cola": "00020101021226640014br.gov.bcb.pix...",
  "qrcode_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
{
  "detail": "API Key ausente"
}
{
  "detail": "Valor deve ser entre R$ 10,00 e R$ 5.000,00"
}
{
  "detail": "Rate limit excedido. Aguarde 60 segundos."
}
Aliases de resposta: Os campos pix_copia_cola e pix_copia_e_cola contêm o mesmo valor (ambos retornados por compatibilidade). O mesmo vale para qrcode_base64 e qr_code_base64.

3. Verificar Status do Pagamento

GET /api/v1/verificar/{pagamento_id} Requer autenticação
Consulta o status de uma cobrança. Use em polling a cada 3–5 segundos enquanto o usuário aguarda o pagamento.
Recomendado: prefira configurar um webhook em vez de polling ativo.
curl https://harpypay.com/api/v1/verificar/pix_live_83921048ab4c \
  -H "X-API-KEY: sk_live_abc123xyz789"
// Polling a cada 4 segundos
const interval = setInterval(async () => {
  const resp = await fetch(`/api/v1/verificar/${pagamentoId}`, {
    headers: { 'X-API-KEY': 'sk_live_abc123xyz789' }
  });
  const { status } = await resp.json();

  if (status === 'Pago') {
    clearInterval(interval);
    window.location.href = '/obrigado';
  } else if (status === 'Expirado') {
    clearInterval(interval);
    alert('Pix expirado, gere uma nova cobrança.');
  }
}, 4000);
{
  "pagamento_id": "pix_live_83921048ab4c",
  "status": "Pago",
  "mensagem": "Pagamento confirmado com sucesso"
}
{
  "pagamento_id": "pix_live_83921048ab4c",
  "status": "Pendente",
  "mensagem": "Aguardando pagamento"
}

4. Configurar Webhook de Confirmação

Quando um Pix é confirmado, a HarpyPay dispara automaticamente um POST para a URL configurada no seu Dashboard. A entrega é garantida por uma fila de retry com tolerância a falhas.

Segurança: O servidor da HarpyPay sempre enviará o header X-Harpy-Signature com um hash HMAC-SHA256 do payload assinado com sua API Key. Sempre valide a assinatura antes de liberar acessos.

Payload recebido no seu servidor

{
  "evento": "pix.pago",
  "pix_id": "pix_live_83921048ab4c",
  "valor": 149.90,
  "valor_liquido": 140.41,
  "status": "Pago"
}
$payload    = file_get_contents('php://input');
$sig_header = $_SERVER['HTTP_X_HARPY_SIGNATURE'] ?? '';
$secret     = 'sua_api_key_aqui';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $sig_header)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

$event = json_decode($payload, true);

if ($event['evento'] === 'pix.pago') {
    // Liberar acesso, marcar pedido como pago etc.
    $pix_id = $event['pix_id'];
    // ... seu código aqui
}

http_response_code(200);
echo 'ok';
import hmac, hashlib
from fastapi import Request, HTTPException

async def webhook_harpypay(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Harpy-Signature", "")
    secret = "sua_api_key_aqui".encode()

    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        raise HTTPException(401, "Assinatura inválida")

    event = await request.json()
    if event["evento"] == "pix.pago":
        pix_id = event["pix_id"]
        # Liberar acesso, atualizar pedido...
    
    return {"ok": True}

5. Split de Receita

O Split permite dividir automaticamente uma transação entre múltiplas contas HarpyPay no momento da confirmação. Ideal para comissões de afiliados, coproduções e marketplace.

Totalmente automático. O split é processado no webhook de confirmação — você não precisa fazer nenhuma chamada adicional. O saldo de cada beneficiário é creditado instantaneamente.

Como funciona o cálculo

O split é calculado sobre o valor líquido da transação (após dedução das taxas da HarpyPay). As porcentagens são relativas ao valor líquido total, e o valor restante é creditado ao lojista principal.

Campo Tipo Descrição
split_rules[].email string E-mail da conta HarpyPay do beneficiário.
split_rules[].porcentagem float Porcentagem do valor líquido a ser transferida. Ex: 30 = 30%.
# Pix de R$ 200,00 com split 30% para um afiliado
curl -X POST https://harpypay.com/api/v1/depositar \
  -H "X-API-KEY: sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 200.00,
    "nome": "Maria Oliveira",
    "cpf": "98765432100",
    "email": "[email protected]",
    "split_rules": [
      {
        "email": "[email protected]",
        "porcentagem": 30
      }
    ]
  }'
import httpx

resp = httpx.post(
    "https://harpypay.com/api/v1/depositar",
    headers={"X-API-KEY": "sk_live_abc123xyz789"},
    json={
        "valor": 200.00,
        "nome": "Maria Oliveira",
        "cpf": "98765432100",
        "email": "[email protected]",
        "split_rules": [
            {"email": "[email protected]", "porcentagem": 30}
        ]
    }
)

print(resp.json())
Exemplo de cálculo: Venda de R$ 200,00 com taxa de 6% + R$ 1,00. Líquido = R$ 187,00. Split 30% para afiliado = R$ 56,10. Lojista recebe = R$ 130,90.

Códigos de Erro

HTTP Mensagem Descrição
200 OK Requisição bem-sucedida.
400 Valor inválido O campo valor está fora do range permitido (R$ 10 a R$ 5.000).
401 API Key ausente Header X-API-KEY não enviado na requisição.
403 API Key inválida / Conta suspensa Chave não encontrada ou conta banida por violação dos Termos de Uso.
403 Transação bloqueada (Antifraude) IP ou CPF do pagador na blacklist MED/BACEN. Não é possível contornar.
429 Rate limit excedido Limite de 20 requisições/minuto por API Key atingido. Aguarde 60s.
503 Sistema em manutenção O gateway está temporariamente indisponível. Verifique harpypay.com/status.

Rate Limiting

Limites aplicados por API Key, janela deslizante de 60 segundos.

POST /api/v1/depositar  — 20 req/min
GET /api/v1/verificar/:id  — 30 req/min