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.
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.
client_secret é exibido uma única vez no momento da criação da chave.
Headers
| Header | Valor |
|---|---|
Authorization | Basic base64(client_id:client_secret) |
Resposta
| Campo | Tipo | Descrição |
|---|---|---|
success | boolean | Indica se a autenticação foi bem-sucedida. |
token | string | Token JWT usado nas demais requisições. |
tokenType | string | Sempre Bearer. |
expiresIn | integer | Validade do token em milissegundos (60000). |
Authorization: Bearer {token} em todas as chamadas seguintes.
credentials=$(echo -n "SUA_API_KEY:SEU_API_SECRET" | base64)
curl -X POST https://api.liontechpay.com/api/auth \
-H "Authorization: Basic $credentials"{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"tokenType": "Bearer",
"expiresIn": 60000
}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 reais | Enviar na API |
|---|---|
| R$ 1,00 | 100 |
| R$ 10,50 | 1050 |
| R$ 150,00 | 15000 |
10.50 será interpretado de forma incorreta — envie 1050.
{
"amountInCents": 15000,
"currency": "BRL"
}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
| Aspecto | Sandbox |
|---|---|
| Endpoints | Os mesmos da produção — só troca a credencial usada em /api/auth. |
| Confirmação de pagamento PIX | Manual, via POST .../pay — não existe confirmação automática nem QR code pagável de verdade. |
| Conclusão de transferência PIX | Manual, via POST .../complete, após passar pelo mesmo fluxo de aprovação da produção. |
| Webhooks | Disparados normalmente — os mesmos eventos (transaction_paid, transfer_completed) que produção enviaria. |
| Dinheiro | Nenhum valor real é movimentado. |
# 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.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.
Corpo da requisição
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
amountInCents | integer | Sim | Valor da cobrança em centavos (mínimo R$ 1,00). |
customer | object | Sim | Dados do pagador. documentType e document são obrigatórios. |
description | string | Não | Até 140 caracteres. Aparece no extrato do pagador. |
postbackUrl | string | Não | URL que recebe a notificação de confirmação do pagamento. |
items | array | Não | Itens do pedido: title, tangible, quantity, amountInCents. |
splits | array | Não | Distribui o valor líquido para outras empresas Lion Tech Pay. A soma não pode passar de 100%. |
Objeto customer
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
documentType | string | Sim | cpf ou cnpj. |
document | string | Sim | Apenas dígitos, sem pontuação. |
name | string | Não | Nome completo do pagador. |
email | string | Não | E-mail válido do pagador. |
phone | string | Não | Telefone de contato. |
billingAddress | object | Não | street, number, neighborhood, city, state, zipCode. |
Objeto splits
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
email | string | Sim | E-mail da empresa Lion Tech Pay que recebe a parte. |
percentage | number | Sim | De 0,01 a 100. A soma dos splits não pode exceder 100%. |
postbackUrl e você não precisa ficar consultando o status — a confirmação chega automaticamente.
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"
}
}'{
"success": true,
"message": "Transação criada com sucesso",
"data": {
"id": "trx_1a2b3c4d5e6f7g8h9i0j",
"pix": {
"emv": "00020126580014br.gov.bcb.pix0136...",
"qrCode": "iVBORw0KGgo..."
},
"status": "pending",
"fees": 0
}
}{
"amountInCents": 5000,
"customer": { "documentType": "cpf", "document": "11122233344" },
"items": [
{
"title": "Produto A",
"tangible": true,
"quantity": 2,
"amountInCents": 2500
}
],
"splits": [
{ "email": "parceiro@empresa.com", "percentage": 30 }
]
}Consultar QR Code#
Consulta uma cobrança PIX criada anteriormente e retorna o EMV, a imagem do QR Code e o status atual.
Parâmetro de rota
| Parâmetro | Tipo | Descrição |
|---|---|---|
transactionId | string | ID da transação retornado na criação do QR Code. |
Status possíveis da transação
| Status | Significado |
|---|---|
pending | Cobrança criada, aguardando pagamento. |
paid | Cobrança paga e liquidada. |
canceled | Cobrança cancelada. |
refunded | Cobrança devolvida ao pagador. |
curl https://api.liontechpay.com/api/v1/pix/in/qrcode/trx_1a2b3c4d5e6f7g8h9i0j \
-H "Authorization: Bearer SEU_TOKEN_AQUI"{
"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
}
}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.
Parâmetro de rota
| Parâmetro | Tipo | Descrição |
|---|---|---|
transactionId | string | ID retornado na criação do QR Code. |
Erros possíveis
| Status | Motivo |
|---|---|
400 | Transação já não está mais pending. |
403 | Transação pertence a uma chave de produção, não sandbox. |
404 | Transação não encontrada. |
curl -X POST https://api.liontechpay.com/api/v1/pix/in/qrcode/trx_1a2b3c4d5e6f7g8h9i0j/pay \
-H "Authorization: Bearer SEU_TOKEN_SANDBOX_AQUI"{
"success": true,
"message": "Pagamento simulado com sucesso",
"data": {
"id": "trx_1a2b3c4d5e6f7g8h9i0j",
"status": "paid",
"endToEndId": "E0000000020260810144500ABCDE123456"
}
}Enviar transferência#
Realiza uma transferência PIX para qualquer chave. A transferência é irreversível após processada.
x-idempotency-key em cada nova transferência.
Tipos de chave PIX aceitos
| Tipo | Formato | Exemplo |
|---|---|---|
| CPF | Apenas dígitos | 11122233344 |
| CNPJ | Apenas dígitos | 11222333000181 |
| E-mail válido | destino@email.com | |
| Telefone | Com +55 | +5511999999999 |
| Chave aleatória | UUID | 123e4567-e89b-... |
Corpo da requisição
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
pixKey | string | Sim | Chave PIX de destino, em qualquer um dos formatos aceitos. |
amount | integer | Sim | Valor da transferência em centavos. |
currency | string | Não | Moeda da operação — BRL. |
description | string | Não | Descrição da transferência. |
postbackUrl | string | Não | URL que recebe a notificação de status da transferência. |
Headers
| Header | Obrig. | Descrição |
|---|---|---|
Authorization | Sim | Bearer {token}. |
Content-Type | Sim | application/json. |
x-idempotency-key | Sim | UUID único por operação. |
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"
}'{
"success": true,
"message": "Transferência criada com sucesso",
"data": {
"id": "transfer_abc123def456",
"status": "pending",
"amount": 10000,
"netAmount": 10000,
"fees": 0,
"pixKey": "fornecedor@exemplo.com"
}
}Consultar transferência#
Consulta uma transferência PIX criada anteriormente e retorna o status atual, o endToEndId e os timestamps de processamento.
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador da transferência. |
status | string | Status atual do processamento. |
amount | integer | Valor bruto em centavos. |
netAmount | integer | Valor líquido em centavos. |
fees | integer | Tarifas aplicadas, em centavos. |
pixKey | string | Chave PIX de destino. |
endToEndId | string · null | Identificador end-to-end no SPI. |
createdAt | date-time | Criação da transferência. |
updatedAt | date-time | Última atualização. |
processedAt | date-time · null | Momento do processamento final. |
Status possíveis da transferência
| Status | Significado |
|---|---|
queued | Na fila para processamento. |
processing | Em processamento interno. |
pending | Aguardando confirmação. |
pending_analysis | Aguardando análise. |
banking_processing | Em processamento bancário. |
banking_refused | Recusada pelo banco. |
banking_error | Erro no processamento bancário. |
manual_analysis | Em análise manual. |
completed | Transferência concluída. |
canceled | Transferência cancelada. |
refused | Transferência recusada. |
error | Erro no processamento. |
curl https://api.liontechpay.com/api/v1/pix/out/pixkey/transfer_abc123def456 \
-H "Authorization: Bearer SEU_TOKEN_AQUI"{
"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"
}
}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.
Parâmetro de rota
| Parâmetro | Tipo | Descrição |
|---|---|---|
transferId | string | ID retornado na criação da transferência. |
Erros possíveis
| Status | Motivo |
|---|---|
400 | Transferência já concluída ou cancelada. |
403 | Transferência pertence a uma chave de produção, não sandbox. |
404 | Transferência não encontrada. |
curl -X POST https://api.liontechpay.com/api/v1/pix/out/pixkey/transfer_abc123def456/complete \
-H "Authorization: Bearer SEU_TOKEN_SANDBOX_AQUI"{
"success": true,
"message": "Transferência concluída com sucesso",
"data": {
"id": "transfer_abc123def456",
"status": "completed",
"endToEndId": "E0000000020260810144500ABCDE654321"
}
}Consultar saldo#
Retorna os saldos atuais das carteiras da empresa autenticada, em reais (string com 2 casas decimais).
Carteiras
| Campo | Descrição |
|---|---|
pix.balance | Saldo livre, disponível para uso e transferências. |
pixBlocked.balance | Saldo bloqueado por cautelar ou MED (indisponível). |
reserve.balance | Valor em reserva, aguardando liquidação. |
"1250.00", e não 125000.
curl https://api.liontechpay.com/api/v1/balance \
-H "Authorization: Bearer SEU_TOKEN_AQUI"{
"success": true,
"data": {
"pix": { "balance": "1250.00" },
"pixBlocked": { "balance": "0.00" },
"reserve": { "balance": "300.00" }
}
}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
| Fluxo | Evento | Disparo |
|---|---|---|
| PIX IN | transaction_created | Cobrança QR Code criada. |
| PIX IN | transaction_paid | Cobrança QR Code paga. |
| PIX IN | transaction_refunded | Cobrança QR Code devolvida. |
| PIX IN | transaction_updated | Status da cobrança QR Code alterado. |
| PIX IN | infraction | Infração/MED criada ou atualizada. |
| PIX OUT | transfer_created | Transferência PIX criada. |
| PIX OUT | transfer_updated | Status da transferência PIX alterado. |
| PIX OUT | transfer_completed | Transferência PIX concluída. |
| PIX OUT | transfer_canceled | Transferência PIX cancelada ou recusada. |
Headers enviados no callback
| Header | Valor |
|---|---|
Content-Type | application/json |
User-Agent | LionTechPay |
Lion-Signature | HMAC-SHA256 no formato t={timestamp},v1={hash} (se configurado) |
2xx imediatamente e faça o processamento pesado depois, de forma assíncrona.
Criar webhook#
Registra um endpoint de webhook. Lion Tech Pay devolve um signatureSecret para validar a assinatura das notificações.
Corpo da requisição
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
url | string | Sim | URL HTTPS que recebe as notificações via POST. |
events | array | Sim | Tipos de evento que disparam a notificação (mínimo 1). |
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | integer | Identificador do webhook. |
name | string · null | Nome do webhook. |
url | string | URL configurada. |
events | array | Eventos assinados. |
isActive | boolean | Se o webhook está ativo. |
signatureSecret | string · null | Segredo usado para validar a assinatura. |
mtlsCapable | boolean · null | Se o endpoint suporta mTLS. |
createdAt | date-time | Data de criação. |
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"]
}'{
"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"
}
}Objeto pagination
| Campo | Tipo | Descrição |
|---|---|---|
offset | integer | Deslocamento inicial da página. |
pageSize | integer | Quantidade de itens por página. |
totalCount | integer | Total de webhooks cadastrados. |
currentPage | integer | Página atual. |
totalPages | integer | Total de páginas. |
hasNext | boolean | Se existe próxima página. |
hasPrevious | boolean | Se existe página anterior. |
curl https://api.liontechpay.com/api/v1/webhook \
-H "Authorization: Bearer SEU_TOKEN_AQUI"{
"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
}
}
}Parâmetro de rota
| Parâmetro | Tipo | Descrição |
|---|---|---|
id | string | Identificador do webhook a ser removido. |
curl -X DELETE https://api.liontechpay.com/api/v1/webhook/webhook_abc123xyz \
-H "Authorization: Bearer SEU_TOKEN_AQUI"{
"success": true
}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.
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
}Formato: pagamento#
Payload dos callbacks de PIX IN — eventos transaction_created, transaction_paid, transaction_refunded, transaction_updated e infraction.
{
"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"
}
}
}
}Formato: transferência#
Payload dos callbacks de PIX OUT — eventos transfer_created, transfer_updated, transfer_completed e transfer_canceled.
{
"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"
}
}
}
}id da transação ou da transferê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ção | Comportamento |
|---|---|
| Mesma chave, retry de rede | Nenhuma transferência duplicada é criada. |
| Mesma chave reaproveitada com corpo diferente | 409 IDEMPOTENCY_CONFLICT. |
| Sem cabeçalho | Cada chamada cria uma nova transferência — sempre envie a chave. |
-H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000"| Status | Código | Significado |
|---|---|---|
| 400 | INVALID_REQUEST | Corpo da requisição inválido — message aponta o campo. |
| 401 | UNAUTHORIZED | Token ausente, inválido ou expirado. |
| 404 | NOT_FOUND | Recurso não encontrado ou pertence a outra conta. |
| 409 | IDEMPOTENCY_CONFLICT | x-idempotency-key reaproveitada com corpo diferente. |
| 429 | RATE_LIMITED | Muitas requisições — tente novamente em alguns minutos. |
{ "error": "NOT_FOUND", "message": "QR Code PIX não encontrado" }