Uma integração que faz sentido.

Primeiros passos

1. Cadastre sua loja e confirme seu e-mail.
2. Em Integrações, crie uma credencial e salve a chave exibida.
3. Escolha as permissões e, se desejar, limite os IPs que podem usá-la.
4. Guarde a chave no servidor da sua loja. Envie Authorization: Bearer SUA_CHAVE em cada chamada.

Base desta instalação: https://www.lynxpay.com.br/api/v1. As respostas JSON não permitem acesso aos dados de outras lojas. O token bruto não é armazenado no banco.

Crie sua primeira cobrança

Use centavos inteiros: R$ 100,00 é 10000. Envie uma chave de idempotência exclusiva para cada pedido, com 8 a 128 caracteres (letras, números, hífen ou sublinhado).

curl -X POST 'https://www.lynxpay.com.br/api/v1/charges' \
  -H 'Authorization: Bearer lp_test_SUA_CHAVE' \
  -H 'Idempotency-Key: pedido-1024' \
  -H 'Content-Type: application/json' \
  --data '{"amount":10000,"description":"Pedido #1024","external_reference":"pedido_1024"}'

Ao repetir a mesma chave e os mesmos dados, a API retorna a cobrança existente. Se alterar os dados e reutilizar a chave, recebe 409 idempotency_conflict.

{
  "id": "chg_IDENTIFICADOR",
  "amount": 10000,
  "fee": 300,
  "net": 9700,
  "status": "pending",
  "kind": "sale",
  "description": "Pedido #1024",
  "external_reference": "pedido_1024",
  "environment": "sandbox",
  "real_payment": false,
  "pix_copy_paste": null,
  "checkout_url": "https://www.lynxpay.com.br/checkout/chg_IDENTIFICADOR",
  "qr_value": "https://www.lynxpay.com.br/checkout/chg_IDENTIFICADOR"
}

A cobrança expira em 15 minutos. No painel autenticado da loja, abra os detalhes e clique em “Confirmar teste”. A confirmação registra uma única entrada no saldo e emite payment.approved. A API pública e o checkout não permitem confirmar pagamentos.

Rotas e permissões

Paginação: offset=0&limit=15, limite máximo de 100 por página. Cobranças aceitam status=paid|pending|cancelled|expired|all e kind=sale|deposit|all. Extrato aceita q, kind, status e datas start=YYYY-MM-DD&end=YYYY-MM-DD. A exportação inclui todos os resultados filtrados, até 10.000 registros.

Webhooks: status=queued|sending|retrying|delivered|failed, type e q. A criação de retiradas, a confirmação de testes e as configurações de segurança são ações do painel autenticado.

Receba eventos na sua loja

Em Integrações → Webhooks, cadastre uma URL HTTPS pública na porta 443 e selecione os eventos. Salve o segredo whsec_… exibido uma única vez. O worker precisa estar em execução para entregar os eventos.

Content-Type: application/json
X-LynxPay-Event: evt_IDENTIFICADOR
X-LynxPay-Timestamp: 1791670000
X-LynxPay-Signature: v1=HMAC_HEXADECIMAL

{
  "id": "evt_IDENTIFICADOR",
  "type": "payment.approved",
  "created_at": "2026-10-11T02:16:40.000Z",
  "environment": "sandbox",
  "real_payment": false,
  "data": {
    "id": "chg_IDENTIFICADOR",
    "amount": 10000, "fee": 300, "net": 9700,
    "currency": "BRL", "status": "paid",
    "external_reference": "pedido_1024"
  }
}

Valide HMAC-SHA256(segredo, timestamp + "." + corpo_original) e compare com a assinatura v1=… em tempo constante. Recuse timestamps distantes mais de 5 minutos e preserve o corpo original, antes de interpretar JSON. O ID do cabeçalho deve coincidir com o ID do corpo.

Registre o ID do evento na mesma transação que atualiza o pedido. Eventos repetidos precisam ser ignorados, respondendo 2xx. O evento contém o ID da cobrança e a referência da sua loja; valide a cobrança conhecida, o valor esperado e o ambiente antes de liberar um produto.

Respostas 2xx confirmam a entrega. Outras respostas, falhas de conexão ou limite de 10 segundos geram novas tentativas: até 8 no total. O worker usa intervalos de 30 segundos, 2 minutos, 10 minutos, 30 minutos, 2 horas, 6 horas e 24 horas. Reenvio manual preserva o ID do evento.

Eventos disponíveis: payment.approved, payment.failed, transfer.approved, withdrawal.completed e pix.infraction. A fila e as tentativas ficam no SQLite, inclusive após reiniciar o servidor.

Proteção da conta e da integração

Use Authenticator na sua conta, guarde os códigos de recuperação e revise suas sessões. Códigos TOTP utilizados não podem ser reutilizados. Cada saque USDT exige senha e um novo código.

As credenciais são armazenadas por hash. Dados pessoais, segredos TOTP, destinos e arquivos enviados são criptografados com a chave privada da instalação. Faça backup do banco, dos arquivos e da chave; mantenha esses backups privados.

Webhooks não aceitam endereços privados, redirecionamentos ou credenciais na URL. O domínio é resolvido novamente no envio, e a conexão HTTPS usa um IP validado. Os cookies do painel são HttpOnly e SameSite; alterações exigem a origem da instalação.

Erros e limites

{
  "error": {
    "message": "Esta credencial não tem a permissão charges:write.",
    "code": "insufficient_scope"
  }
}

401 pede uma chave ou sessão válida; 403 indica permissão ou origem incorreta; 404 indica registro não encontrado na sua conta; 409 indica conflito; 422 indica dados inválidos; 429 indica limite de tentativas; 503 indica um serviço configurável indisponível.

A API permite 120 requisições por minuto por credencial. Use consultas com intervalo, preserve a idempotência ao repetir chamadas e acompanhe o webhook para mudanças de estado.

O ZIP da LynxPay inclui os exemplos examples/loja.mjs e examples/webhook-verificar.mjs, além dos guias de instalação e hospedagem.