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
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 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.
| Escopo | Permite |
|---|---|
| payments:create | criar pagamentos |
| payments:read | consultar e listar pagamentos |
| payouts:create | criar saques |
| payouts:read | consultar e listar saques |
| balance:read | consultar saldo |
| account:read | conta, taxas, limites e status |
| transactions:read | listar 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.
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 -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.
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Saldo insuficiente para o saque e a taxa.",
"requestId": "req_9f2a1c7b"
}
}| HTTP | code | Quando acontece |
|---|---|---|
| 401 | UNAUTHENTICATED | chave ausente |
| 401 | INVALID_API_KEY | chave inválida ou revogada |
| 403 | SCOPE_REQUIRED | chave sem o escopo da rota |
| 403 | ACCOUNT_BLOCKED | conta bloqueada |
| 400 | INVALID_AMOUNT | valor fora da faixa permitida |
| 400 | INVALID_PIX_KEY | chave Pix não confere com o tipo |
| 409 | INSUFFICIENT_BALANCE | saldo insuficiente para saque + taxa |
| 404 | NOT_FOUND | recurso não encontrado |
| 429 | RATE_LIMITED | limite de chamadas excedido |
| 502 | ACQUIRER_UNAVAILABLE | adquirente indisponível no momento |
| 503 | SERVICE_UNAVAILABLE | gateway 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.
/v1/paymentsCorpo
| Campo | Tipo | |
|---|---|---|
| amount reais | number | obrigatório |
| identification | string | sua referência |
| validityMinutes | number | validade (padrão 60) |
| payer.name | string | opcional |
| payer.document | string | CPF/CNPJ, opcional |
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" }
}'{
"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.
/v1/payments/{id}{
"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.
/v1/payments?status=paid&limit=20&offset=0{
"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.
/v1/payoutsCorpo
| Campo | Tipo | |
|---|---|---|
| amount reais | number | obrigatório |
| pixKey | string | obrigatório |
| pixKeyType | string | obrigatório |
| beneficiaryName | string | recomendado |
pixKeyType: cpf, cnpj, email, phone ou random.
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"
}'{
"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.
/v1/payouts/{id}status: processing, paid ou failed.
Listar saques
Escopo: payouts:read. Mesmos filtros de paginação dos pagamentos.
/v1/payouts?limit=20&offset=0Comprovante de saque
Retorna os dados do comprovante, incluindo o endToEndId do Pix. Escopo: payouts:read.
/v1/payouts/{id}/receipt{
"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.
/v1/balance{
"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.
/v1/account{
"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.
/v1/account/fees-limits{
"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.
/v1/status{
"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.
/v1/transactions?type=deposit&status=paidConsultar transação
Escopo: transactions:read.
/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çalho | Conteúdo |
|---|---|
| X-Kyvopay-Signature | HMAC-SHA256 (hex) de timestamp.corpo |
| X-Kyvopay-Timestamp | unix time do envio |
| X-Kyvopay-Delivery | id único da entrega (deduplicação) |
Corpo do evento
{
"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
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));
}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.