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.
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)
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. |
| 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."
}
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
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.
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.
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())
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