Lion Tech PayAPI Docs
Base URL https://api.liontechpay.com
Documentação da API · v1

Receba e envie pagamentos PIX com a API Lion Tech Pay

Infraestrutura de pagamentos para empresas que constroem o futuro. Cobranças PIX dinâmicas, transferências para qualquer chave, saldo em tempo real e webhooks assinados — em uma API REST, sem SDK obrigatório.

Cobranças PIX dinâmicas Transferências para qualquer chave Saldo em tempo real Webhooks assinados
Base URL
https://api.liontechpay.com
NotaAcesse o Dashboard e gere suas credenciais em Configurações → API Keys antes de começar.
Começando

Autenticação#

Gera um token JWT para autenticar as demais requisições. Concatene client_id:client_secret, codifique em Base64 e envie como Basic Auth.

POST /api/auth
Guarde com cuidadoO client_secret é exibido uma única vez no momento da criação da chave.

Headers

HeaderValor
AuthorizationBasic base64(client_id:client_secret)

Resposta

CampoTipoDescrição
successbooleanIndica se a autenticação foi bem-sucedida.
tokenstringToken JWT usado nas demais requisições.
tokenTypestringSempre Bearer.
expiresInintegerValidade do token em milissegundos (60000).
Como usarUse o token retornado como Authorization: Bearer {token} em todas as chamadas seguintes.
requestcURL
credentials=$(echo -n "SUA_API_KEY:SEU_API_SECRET" | base64)

curl -X POST https://api.liontechpay.com/api/auth \
  -H "Authorization: Basic $credentials"
response200 OK
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 60000
}
Começando

Valores monetários#

Todos os valores enviados e recebidos pela API são centavos, em inteiros — nunca reais fracionados. A única exceção é o endpoint de saldo, que retorna reais como string com duas casas decimais.

Valor em reaisEnviar na API
R$ 1,00100
R$ 10,501050
R$ 150,0015000
AtençãoNunca envie valores com ponto ou vírgula decimal. 10.50 será interpretado de forma incorreta — envie 1050.
exemploJSON
{
  "amountInCents": 15000,
  "currency": "BRL"
}
Começando

Ambiente Sandbox#

Um segundo par de credenciais, isolado da produção, que transaciona apenas contra um adquirente simulado. Nenhuma transação sandbox movimenta dinheiro real, e nada dos seus dados de produção é compartilhado — company, saldo, cobranças e transferências vivem em um escopo totalmente separado.

Como ativar

No Dashboard, acesse Chaves de API → Sandbox e clique em Ativar ambiente sandbox. Um novo client_id/client_secret é gerado — use-os em POST /api/auth exatamente como faria com as credenciais de produção.

O que muda

AspectoSandbox
EndpointsOs mesmos da produção — só troca a credencial usada em /api/auth.
Confirmação de pagamento PIXManual, via POST .../pay — não existe confirmação automática nem QR code pagável de verdade.
Conclusão de transferência PIXManual, via POST .../complete, após passar pelo mesmo fluxo de aprovação da produção.
WebhooksDisparados normalmente — os mesmos eventos (transaction_paid, transfer_completed) que produção enviaria.
DinheiroNenhum valor real é movimentado.
DicaUse o botão Testar API no Dashboard para gerar uma cobrança sandbox e simular o pagamento sem escrever nenhum código.
fluxo completobash
# 1. Autentique com a credencial sandbox
TOKEN=$(curl -s -X POST https://api.liontechpay.com/api/auth \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID_SANDBOX:CLIENT_SECRET_SANDBOX' | base64)" \
  | jq -r .token)

# 2. Crie uma cobrança normalmente
TRX=$(curl -s -X POST https://api.liontechpay.com/api/v1/pix/in/qrcode \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amountInCents": 5000, "customer": {"documentType": "cpf", "document": "11122233344"}}' \
  | jq -r .data.id)

# 3. Simule o pagamento manualmente
curl -X POST https://api.liontechpay.com/api/v1/pix/in/qrcode/$TRX/pay \
  -H "Authorization: Bearer $TOKEN"

# O webhook transaction_paid é disparado normalmente.
PIX IN · Receber

Criar QR Code#

Cria um QR Code PIX para receber um pagamento imediato. Retorna o código EMV (copia e cola) e a imagem do QR Code em Base64, pronta para exibir.

POST /api/v1/pix/in/qrcode

Corpo da requisição

CampoTipoObrig.Descrição
amountInCentsintegerSimValor da cobrança em centavos (mínimo R$ 1,00).
customerobjectSimDados do pagador. documentType e document são obrigatórios.
descriptionstringNãoAté 140 caracteres. Aparece no extrato do pagador.
postbackUrlstringNãoURL que recebe a notificação de confirmação do pagamento.
itemsarrayNãoItens do pedido: title, tangible, quantity, amountInCents.
splitsarrayNãoDistribui o valor líquido para outras empresas Lion Tech Pay. A soma não pode passar de 100%.

Objeto customer

CampoTipoObrig.Descrição
documentTypestringSimcpf ou cnpj.
documentstringSimApenas dígitos, sem pontuação.
namestringNãoNome completo do pagador.
emailstringNãoE-mail válido do pagador.
phonestringNãoTelefone de contato.
billingAddressobjectNãostreet, number, neighborhood, city, state, zipCode.

Objeto splits

CampoTipoObrig.Descrição
emailstringSimE-mail da empresa Lion Tech Pay que recebe a parte.
percentagenumberSimDe 0,01 a 100. A soma dos splits não pode exceder 100%.
DicaInforme postbackUrl e você não precisa ficar consultando o status — a confirmação chega automaticamente.
requestcURL
curl -X POST https://api.liontechpay.com/api/v1/pix/in/qrcode \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "description": "Pagamento de servicos",
    "postbackUrl": "https://exemplo.com.br/webhook",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@exemplo.com",
      "documentType": "cpf",
      "document": "11122233344",
      "phone": "(11) 91234-5678"
    }
  }'
response200 OK
{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "pix": {
      "emv": "00020126580014br.gov.bcb.pix0136...",
      "qrCode": "iVBORw0KGgo..."
    },
    "status": "pending",
    "fees": 0
  }
}
splits + itemsopcional
{
  "amountInCents": 5000,
  "customer": { "documentType": "cpf", "document": "11122233344" },
  "items": [
    {
      "title": "Produto A",
      "tangible": true,
      "quantity": 2,
      "amountInCents": 2500
    }
  ],
  "splits": [
    { "email": "parceiro@empresa.com", "percentage": 30 }
  ]
}
PIX IN · Receber

Consultar QR Code#

Consulta uma cobrança PIX criada anteriormente e retorna o EMV, a imagem do QR Code e o status atual.

GET /api/v1/pix/in/qrcode/:transactionId

Parâmetro de rota

ParâmetroTipoDescrição
transactionIdstringID da transação retornado na criação do QR Code.

Status possíveis da transação

StatusSignificado
pendingCobrança criada, aguardando pagamento.
paidCobrança paga e liquidada.
canceledCobrança cancelada.
refundedCobrança devolvida ao pagador.
requestcURL
curl https://api.liontechpay.com/api/v1/pix/in/qrcode/trx_1a2b3c4d5e6f7g8h9i0j \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
response200 OK
{
  "success": true,
  "message": "QR Code PIX encontrado com sucesso",
  "data": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "pix": {
      "emv": "00020126580014br.gov.bcb.pix0136...",
      "qrCode": "iVBORw0KGgo..."
    },
    "status": "pending",
    "fees": 0
  }
}
PIX IN · Sandbox

Simular pagamento#

Confirma manualmente o pagamento de uma cobrança criada com uma chave sandbox. Dispara o mesmo webhook transaction_paid que produção enviaria. Só funciona para transações sandbox — retorna 403 caso contrário.

POST /api/v1/pix/in/qrcode/:transactionId/pay

Parâmetro de rota

ParâmetroTipoDescrição
transactionIdstringID retornado na criação do QR Code.

Erros possíveis

StatusMotivo
400Transação já não está mais pending.
403Transação pertence a uma chave de produção, não sandbox.
404Transação não encontrada.
requestcURL
curl -X POST https://api.liontechpay.com/api/v1/pix/in/qrcode/trx_1a2b3c4d5e6f7g8h9i0j/pay \
  -H "Authorization: Bearer SEU_TOKEN_SANDBOX_AQUI"
response200 OK
{
  "success": true,
  "message": "Pagamento simulado com sucesso",
  "data": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "status": "paid",
    "endToEndId": "E0000000020260810144500ABCDE123456"
  }
}
PIX OUT · Enviar

Enviar transferência#

Realiza uma transferência PIX para qualquer chave. A transferência é irreversível após processada.

POST /api/v1/pix/out/pixkey
Idempotência obrigatóriaEnvie um UUID único no header x-idempotency-key em cada nova transferência.

Tipos de chave PIX aceitos

TipoFormatoExemplo
CPFApenas dígitos11122233344
CNPJApenas dígitos11222333000181
E-mailE-mail válidodestino@email.com
TelefoneCom +55+5511999999999
Chave aleatóriaUUID123e4567-e89b-...

Corpo da requisição

CampoTipoObrig.Descrição
pixKeystringSimChave PIX de destino, em qualquer um dos formatos aceitos.
amountintegerSimValor da transferência em centavos.
currencystringNãoMoeda da operação — BRL.
descriptionstringNãoDescrição da transferência.
postbackUrlstringNãoURL que recebe a notificação de status da transferência.

Headers

HeaderObrig.Descrição
AuthorizationSimBearer {token}.
Content-TypeSimapplication/json.
x-idempotency-keySimUUID único por operação.
requestcURL
curl -X POST https://api.liontechpay.com/api/v1/pix/out/pixkey \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "pixKey": "fornecedor@exemplo.com",
    "amount": 10000,
    "currency": "BRL",
    "description": "Pagamento de fornecedor",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
  }'
response200 OK
{
  "success": true,
  "message": "Transferência criada com sucesso",
  "data": {
    "id": "transfer_abc123def456",
    "status": "pending",
    "amount": 10000,
    "netAmount": 10000,
    "fees": 0,
    "pixKey": "fornecedor@exemplo.com"
  }
}
PIX OUT · Enviar

Consultar transferência#

Consulta uma transferência PIX criada anteriormente e retorna o status atual, o endToEndId e os timestamps de processamento.

GET /api/v1/pix/out/pixkey/:transferId

Campos da resposta

CampoTipoDescrição
idstringIdentificador da transferência.
statusstringStatus atual do processamento.
amountintegerValor bruto em centavos.
netAmountintegerValor líquido em centavos.
feesintegerTarifas aplicadas, em centavos.
pixKeystringChave PIX de destino.
endToEndIdstring · nullIdentificador end-to-end no SPI.
createdAtdate-timeCriação da transferência.
updatedAtdate-timeÚltima atualização.
processedAtdate-time · nullMomento do processamento final.

Status possíveis da transferência

StatusSignificado
queuedNa fila para processamento.
processingEm processamento interno.
pendingAguardando confirmação.
pending_analysisAguardando análise.
banking_processingEm processamento bancário.
banking_refusedRecusada pelo banco.
banking_errorErro no processamento bancário.
manual_analysisEm análise manual.
completedTransferência concluída.
canceledTransferência cancelada.
refusedTransferência recusada.
errorErro no processamento.
requestcURL
curl https://api.liontechpay.com/api/v1/pix/out/pixkey/transfer_abc123def456 \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
response200 OK
{
  "success": true,
  "data": {
    "id": "transfer_abc123def456",
    "status": "completed",
    "amount": 10000,
    "netAmount": 10000,
    "fees": 0,
    "pixKey": "fornecedor@exemplo.com",
    "endToEndId": "E1234567820241231000000000000002",
    "createdAt": "2026-01-15T13:44:25.838Z",
    "updatedAt": "2026-01-15T13:45:10.120Z",
    "processedAt": "2026-01-15T13:45:10.120Z"
  }
}
PIX OUT · Sandbox

Simular conclusão#

Confirma manualmente a conclusão de uma transferência criada com uma chave sandbox. Dispara o mesmo webhook transfer_completed que produção enviaria. A transferência precisa ter saído de pending/manual_analysis primeiro — sandbox segue o mesmo fluxo de aprovação da produção.

POST /api/v1/pix/out/pixkey/:transferId/complete

Parâmetro de rota

ParâmetroTipoDescrição
transferIdstringID retornado na criação da transferência.

Erros possíveis

StatusMotivo
400Transferência já concluída ou cancelada.
403Transferência pertence a uma chave de produção, não sandbox.
404Transferência não encontrada.
requestcURL
curl -X POST https://api.liontechpay.com/api/v1/pix/out/pixkey/transfer_abc123def456/complete \
  -H "Authorization: Bearer SEU_TOKEN_SANDBOX_AQUI"
response200 OK
{
  "success": true,
  "message": "Transferência concluída com sucesso",
  "data": {
    "id": "transfer_abc123def456",
    "status": "completed",
    "endToEndId": "E0000000020260810144500ABCDE654321"
  }
}
Conta

Consultar saldo#

Retorna os saldos atuais das carteiras da empresa autenticada, em reais (string com 2 casas decimais).

GET /api/v1/balance

Carteiras

CampoDescrição
pix.balanceSaldo livre, disponível para uso e transferências.
pixBlocked.balanceSaldo bloqueado por cautelar ou MED (indisponível).
reserve.balanceValor em reserva, aguardando liquidação.
Exceção à regra de centavosEste é o único endpoint que devolve reais como string — "1250.00", e não 125000.
requestcURL
curl https://api.liontechpay.com/api/v1/balance \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
response200 OK
{
  "success": true,
  "data": {
    "pix": { "balance": "1250.00" },
    "pixBlocked": { "balance": "0.00" },
    "reserve": { "balance": "300.00" }
  }
}
Webhooks

Como funcionam#

Receba notificações em tempo real sobre eventos da sua conta. Configure uma URL e escolha quais eventos deseja monitorar. Lion Tech Pay envia requisições POST assinadas — responda rápido com 2xx e processe o restante de forma assíncrona.

Eventos disponíveis

FluxoEventoDisparo
PIX INtransaction_createdCobrança QR Code criada.
PIX INtransaction_paidCobrança QR Code paga.
PIX INtransaction_refundedCobrança QR Code devolvida.
PIX INtransaction_updatedStatus da cobrança QR Code alterado.
PIX INinfractionInfração/MED criada ou atualizada.
PIX OUTtransfer_createdTransferência PIX criada.
PIX OUTtransfer_updatedStatus da transferência PIX alterado.
PIX OUTtransfer_completedTransferência PIX concluída.
PIX OUTtransfer_canceledTransferência PIX cancelada ou recusada.

Headers enviados no callback

HeaderValor
Content-Typeapplication/json
User-AgentLionTechPay
Lion-SignatureHMAC-SHA256 no formato t={timestamp},v1={hash} (se configurado)
Responda rápidoRetorne 2xx imediatamente e faça o processamento pesado depois, de forma assíncrona.
Webhooks

Criar webhook#

Registra um endpoint de webhook. Lion Tech Pay devolve um signatureSecret para validar a assinatura das notificações.

POST /api/v1/webhook

Corpo da requisição

CampoTipoObrig.Descrição
urlstringSimURL HTTPS que recebe as notificações via POST.
eventsarraySimTipos de evento que disparam a notificação (mínimo 1).

Campos da resposta

CampoTipoDescrição
idintegerIdentificador do webhook.
namestring · nullNome do webhook.
urlstringURL configurada.
eventsarrayEventos assinados.
isActivebooleanSe o webhook está ativo.
signatureSecretstring · nullSegredo usado para validar a assinatura.
mtlsCapableboolean · nullSe o endpoint suporta mTLS.
createdAtdate-timeData de criação.
requestcURL
curl -X POST https://api.liontechpay.com/api/v1/webhook \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemplo.com.br/webhook",
    "events": ["transaction_paid", "transfer_completed"]
  }'
response201 Created
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Meu webhook",
    "url": "https://exemplo.com.br/webhook",
    "events": ["transaction_paid", "transfer_completed"],
    "isActive": true,
    "signatureSecret": "secret_abc123",
    "mtlsCapable": false,
    "createdAt": "2024-12-31T12:00:00Z"
  }
}
Webhooks

Listar webhooks#

Retorna todos os webhooks configurados na conta, com paginação.

GET /api/v1/webhook

Objeto pagination

CampoTipoDescrição
offsetintegerDeslocamento inicial da página.
pageSizeintegerQuantidade de itens por página.
totalCountintegerTotal de webhooks cadastrados.
currentPageintegerPágina atual.
totalPagesintegerTotal de páginas.
hasNextbooleanSe existe próxima página.
hasPreviousbooleanSe existe página anterior.
requestcURL
curl https://api.liontechpay.com/api/v1/webhook \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
response200 OK
{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": 123,
        "name": "Meu webhook",
        "url": "https://exemplo.com.br/webhook",
        "events": ["transaction_paid", "transfer_completed"],
        "isActive": true,
        "signatureSecret": "secret_abc123",
        "mtlsCapable": false,
        "createdAt": "2024-12-31T12:00:00Z"
      }
    ],
    "pagination": {
      "offset": 0,
      "pageSize": 10,
      "totalCount": 1,
      "currentPage": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}
Webhooks

Remover webhook#

Remove permanentemente um webhook da conta.

DELETE /api/v1/webhook/:id
Ação irreversívelO webhook deixa de receber notificações imediatamente após a remoção. Não é possível desfazer.

Parâmetro de rota

ParâmetroTipoDescrição
idstringIdentificador do webhook a ser removido.
requestcURL
curl -X DELETE https://api.liontechpay.com/api/v1/webhook/webhook_abc123xyz \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
response200 OK
{
  "success": true
}
Webhooks

Verificando a assinatura#

Todo POST chega com o header Lion-Signature no formato t=<epoch>,v1=<hmac>. Recalcule o HMAC-SHA256 sobre {timestamp}.{corpo bruto} usando o seu signatureSecret e compare em tempo constante — nunca com o operador de igualdade direto.

Use o corpo brutoValide sobre o corpo da requisição antes do parse de JSON. Reserializar o objeto muda a sequência de bytes e invalida a assinatura.
verify-signature.jsNode.js
const crypto = require('crypto')

function isValidLionWebhook(payload, signature, secret) {
  const [timestampPart, signaturePart] = signature.split(',')
  const timestamp = timestampPart.replace('t=', '')
  const receivedSignature = signaturePart.replace('v1=', '')

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex')

  return expected === receivedSignature
}
Webhooks

Formato: pagamento#

Payload dos callbacks de PIX IN — eventos transaction_created, transaction_paid, transaction_refunded, transaction_updated e infraction.

POST · seu endpointbody
{
  "id": "8d0f3b8f-5c2f-4a10-8dd6-8bbf5e9b1d11",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "transaction_abc123",
    "amount": 5000,
    "status": "paid",
    "pix": {
      "endToEndId": "E1234567820241231000000000000001",
      "payerInfo": {
        "name": "Joao Silva",
        "document": "11122233344"
      }
    }
  }
}
Webhooks

Formato: transferência#

Payload dos callbacks de PIX OUT — eventos transfer_created, transfer_updated, transfer_completed e transfer_canceled.

POST · seu endpointbody
{
  "id": "5f9e0c94-60a4-4df8-bb81-7f6efc6f61b0",
  "type": "transfer",
  "event": "transfer_completed",
  "scope": "user",
  "transfer": {
    "id": "transfer_abc123",
    "amount": 10000,
    "status": "paid",
    "pix": {
      "endToEndId": "E1234567820241231000000000000002",
      "creditorAccount": {
        "name": "Fornecedor Exemplo",
        "document": "12345678000199"
      }
    }
  }
}
ReentregaEm caso de falha na entrega, o mesmo evento pode ser reenviado. Processe de forma idempotente pelo id da transação ou da transferência.
Referência

Idempotência#

Para transferências PIX, envie o header x-idempotency-key com um UUID único por operação para garantir que não haja duplicação em caso de retry.

SituaçãoComportamento
Mesma chave, retry de redeNenhuma transferência duplicada é criada.
Mesma chave reaproveitada com corpo diferente409 IDEMPOTENCY_CONFLICT.
Sem cabeçalhoCada chamada cria uma nova transferência — sempre envie a chave.
headerexemplo
-H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000"
Referência

Erros#

Erros sempre respondem em JSON com os campos error (código) e message (legível).

StatusCódigoSignificado
400INVALID_REQUESTCorpo da requisição inválido — message aponta o campo.
401UNAUTHORIZEDToken ausente, inválido ou expirado.
404NOT_FOUNDRecurso não encontrado ou pertence a outra conta.
409IDEMPOTENCY_CONFLICTx-idempotency-key reaproveitada com corpo diferente.
429RATE_LIMITEDMuitas requisições — tente novamente em alguns minutos.
responseerro
{ "error": "NOT_FOUND", "message": "QR Code PIX não encontrado" }
Referência

Endpoints#

Referência rápida de todas as rotas disponíveis na API Lion Tech Pay.

Lion Tech Pay · Documentação da API v1
Infraestrutura de pagamentos para empresas que constroem o futuro.
Copiado