lovinpayDocsEntrar

Documentação da API

A LovinPay é uma infraestrutura de pagamentos Pix. Com uma única chave de API você cria cobranças (Pix de entrada), envia saques (Pix de saída), consulta saldo e recebe confirmações por webhook — tudo em reais, com respostas previsíveis e idempotência de ponta a ponta.

Como funciona

  • Você cria uma chave de API no painel e define os escopos dela.
  • Chama a API para criar um pagamento: recebe o QR Code e o copia-e-cola para o seu cliente pagar.
  • Quando o Pix é confirmado, a LovinPay credita o valor e dispara um webhook assinado para o seu sistema.
  • Para pagar terceiros, você cria um saque para uma chave Pix; o valor sai do seu saldo disponível.

URL base

Base URL
https://api.lovinpay.com.br

Todas as rotas abaixo são relativas a essa URL. O corpo e as respostas são sempre application/json, e os valores monetários estão em reais (ex.: 25.94 = R$ 25,94).

Autenticação

Toda requisição às rotas /v1/* precisa da sua chave de API no cabeçalho X-API-Key (também aceitamos Authorization: Bearer). A chave é guardada apenas como hash — nem a LovinPay consegue lê-la depois de criada, então guarde-a com segurança.

cURL
curl https://api.lovinpay.com.br/v1/balance \
  -H "X-API-Key: lp_live_sua_chave_aqui"

Escopos

Cada chave carrega apenas os escopos que você liberar. Uma chamada a uma rota fora do escopo da chave recebe 403 SCOPE_REQUIRED.

EscopoPermite
payments:createcriar pagamentos
payments:readconsultar e listar pagamentos
payouts:createcriar saques
payouts:readconsultar e listar saques
balance:readconsultar saldo
account:readconta, taxas, limites e status
transactions:readlistar e consultar transações

Ambiente

Cada chave pertence a um ambiente. Em homologação você integra e testa sem mover dinheiro de verdade; em produção as cobranças e os saques são reais. O ambiente da chave aparece em GET /v1/account e em GET /v1/status.

Dinheiro é sempre tratado como centavos inteiros por dentro; no JSON ele aparece como número em reais com duas casas. A moeda é sempre BRL.

Idempotência

Para criar pagamentos e saques com segurança contra repetição de requisição (timeout, retry), envie o cabeçalho Idempotency-Key com um valor único por operação. Se a mesma chave chegar duas vezes, a LovinPay devolve a mesma transação em vez de criar outra.

cURL
curl -X POST https://api.lovinpay.com.br/v1/payments \
  -H "X-API-Key: lp_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-1024" \
  -H "Content-Type: application/json" \
  -d '{"amount":25.94,"identification":"Pedido 1024"}'

Limite de uso

Cada chave pode fazer até 60 requisições por minuto. Ao estourar, a resposta é 429 RATE_LIMITED com o cabeçalho Retry-After indicando quantos segundos aguardar. Toda resposta também traz X-Request-ID, útil para suporte.

Erros

Erros seguem sempre o mesmo formato, com um code estável para o seu código tratar e um requestId para rastrear.

Formato de erro
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo insuficiente para o saque e a taxa.",
    "requestId": "req_9f2a1c7b"
  }
}
HTTPcodeQuando acontece
401UNAUTHENTICATEDchave ausente
401INVALID_API_KEYchave inválida ou revogada
403SCOPE_REQUIREDchave sem o escopo da rota
403ACCOUNT_BLOCKEDconta bloqueada
400INVALID_AMOUNTvalor fora da faixa permitida
400INVALID_PIX_KEYchave Pix não confere com o tipo
409INSUFFICIENT_BALANCEsaldo insuficiente para saque + taxa
404NOT_FOUNDrecurso não encontrado
429RATE_LIMITEDlimite de chamadas excedido
502ACQUIRER_UNAVAILABLEadquirente indisponível no momento
503SERVICE_UNAVAILABLEgateway em manutenção

Criar pagamento

Gera uma cobrança Pix e devolve o QR Code (imagem) e o copia-e-cola para o cliente pagar. Escopo: payments:create.

POST/v1/payments

Corpo

CampoTipo
amount reaisnumberobrigatório
identificationstringsua referência
validityMinutesnumbervalidade (padrão 60)
payer.namestringopcional
payer.documentstringCPF/CNPJ, opcional
cURL
curl -X POST https://api.lovinpay.com.br/v1/payments \
  -H "X-API-Key: $LP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.94,
    "identification": "Pedido 1024",
    "validityMinutes": 60,
    "payer": { "name": "Ana Lima", "document": "12345678909" }
  }'
Resposta201 Created
{
  "id": "txn_3b1c...",
  "type": "deposit",
  "status": "pending",
  "amount": 25.94,
  "fee": 0.40,
  "netAmount": 25.54,
  "identification": "Pedido 1024",
  "pixCode": "00020126...5204000053039865802BR...",
  "qrCodeImage": "data:image/png;base64,iVBORw0...",
  "expiresAt": "2026-11-20T18:00:00Z",
  "createdAt": "2026-11-20T17:00:00Z"
}

Consultar pagamento

Escopo: payments:read.

GET/v1/payments/{id}
Resposta200 OK
{
  "id": "txn_3b1c...",
  "type": "deposit",
  "status": "paid",
  "amount": 25.94,
  "fee": 0.40,
  "netAmount": 25.54,
  "identification": "Pedido 1024",
  "paidAt": "2026-11-20T17:03:11Z",
  "createdAt": "2026-11-20T17:00:00Z"
}

status: pending, paid, expired, cancelled, refunded ou failed.

Listar pagamentos

Escopo: payments:read. Filtros por query: status, limit (padrão 50) e offset.

GET/v1/payments?status=paid&limit=20&offset=0
Resposta200 OK
{
  "data": [ { "id": "txn_3b1c...", "status": "paid", "amount": 25.94, "...": "..." } ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Criar saque

Envia um Pix para uma chave. A taxa de saque é somada: debita-se amount + fee do seu saldo e o beneficiário recebe o valor cheio. Sem saldo suficiente, a resposta é 409 INSUFFICIENT_BALANCE. Escopo: payouts:create.

POST/v1/payouts

Corpo

CampoTipo
amount reaisnumberobrigatório
pixKeystringobrigatório
pixKeyTypestringobrigatório
beneficiaryNamestringrecomendado

pixKeyType: cpf, cnpj, email, phone ou random.

cURL
curl -X POST https://api.lovinpay.com.br/v1/payouts \
  -H "X-API-Key: $LP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "pixKey": "[email protected]",
    "pixKeyType": "email",
    "beneficiaryName": "Ana Lima"
  }'
Resposta201 Created
{
  "id": "txn_7d2e...",
  "type": "withdrawal",
  "status": "processing",
  "netAmount": 10.00,
  "fee": 1.10,
  "totalAmount": 11.10,
  "pixKey": "[email protected]",
  "pixKeyType": "email",
  "beneficiaryName": "Ana Lima",
  "endToEndId": "E12345678...",
  "createdAt": "2026-11-20T17:10:00Z"
}

Consultar saque

Escopo: payouts:read.

GET/v1/payouts/{id}

status: processing, paid ou failed.

Listar saques

Escopo: payouts:read. Mesmos filtros de paginação dos pagamentos.

GET/v1/payouts?limit=20&offset=0

Comprovante de saque

Retorna os dados do comprovante, incluindo o endToEndId do Pix. Escopo: payouts:read.

GET/v1/payouts/{id}/receipt
Resposta200 OK
{
  "payoutId": "txn_7d2e...",
  "status": "paid",
  "endToEndId": "E12345678202611201710...",
  "amount": 10.00,
  "fee": 1.10,
  "totalAmount": 11.10,
  "pixKey": "[email protected]",
  "pixKeyType": "email",
  "beneficiaryName": "Ana Lima",
  "createdAt": "2026-11-20T17:10:00Z"
}

Saldo

Escopo: balance:read.

GET/v1/balance
Resposta200 OK
{
  "availableBalance": 123.45,
  "reservedBalance": 10.00,
  "currency": "BRL"
}

availableBalance é o que você pode sacar; reservedBalance são saques em processamento, já descontados do disponível.

Dados da conta

Escopo: account:read.

GET/v1/account
Resposta200 OK
{
  "accountId": "loj_a1b2...",
  "name": "Loja do Fulano",
  "environment": "production",
  "blocked": false,
  "verificationRequired": true,
  "verificationStatus": "required",
  "availableBalance": 123.45,
  "reservedBalance": 10.00,
  "currency": "BRL"
}

Taxas e limites

Escopo: account:read.

GET/v1/account/fees-limits
Resposta200 OK
{
  "deposit": { "fixed": 0.40, "percentage": 0 },
  "withdrawal": { "fixed": 0, "percentage": 0 },
  "limits": { "minPerTransaction": 0.01, "maxPerTransaction": 1000000.00 },
  "currency": "BRL"
}

Status

Estado operacional da API para a sua conta. Escopo: account:read.

GET/v1/status
Resposta200 OK
{
  "status": "operational",
  "environment": "production",
  "apiVersion": "v1",
  "timestamp": "2026-11-20T17:00:00Z"
}

Listar transações

Lista unificada de pagamentos e saques. Escopo: transactions:read. Filtros: type (deposit ou withdrawal), status, limit, offset.

GET/v1/transactions?type=deposit&status=paid

Consultar transação

Escopo: transactions:read.

GET/v1/transactions/{id}

Webhooks

Quando o estado de uma transação muda (por exemplo, um Pix é pago), a LovinPay envia um POST para a URL de webhook cadastrada no seu painel. Cada envio é assinado para você confirmar que veio mesmo da LovinPay e não foi forjado nem repetido.

Cabeçalhos

CabeçalhoConteúdo
X-Kyvopay-SignatureHMAC-SHA256 (hex) de timestamp.corpo
X-Kyvopay-Timestampunix time do envio
X-Kyvopay-Deliveryid único da entrega (deduplicação)

Corpo do evento

POST para a sua URL
{
  "event": "payment.paid",
  "data": {
    "id": "txn_3b1c...",
    "type": "deposit",
    "status": "paid",
    "amount": 25.94,
    "fee": 0.40,
    "netAmount": 25.54,
    "identification": "Pedido 1024",
    "paidAt": "2026-11-20T17:03:11Z"
  },
  "sentAt": "2026-11-20T17:03:12Z"
}

Validando a assinatura

Node.js
import crypto from "node:crypto";

function valido(req, segredo) {
  const ts = req.headers["x-kyvopay-timestamp"];
  const assinatura = req.headers["x-kyvopay-signature"];
  const base = ts + "." + req.rawBody; // corpo bruto, sem reparsear
  const esperado = crypto.createHmac("sha256", segredo)
    .update(base).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(assinatura), Buffer.from(esperado));
}
Responda 2xx rápido. Se a sua URL não responder 2xx, a LovinPay considera a entrega falha e pode reenviar — por isso o X-Kyvopay-Delivery serve para você ignorar duplicatas.

Integrar com IA

A documentação da LovinPay também foi pensada para LLMs lerem. Cole o link de contexto na sua IA favorita e peça a integração — ela entende o contrato inteiro.