API da LastroPay

Introdução

A API da LastroPay é REST, recebe e devolve JSON em UTF-8 e usa os códigos HTTP padrão. Com ela o seu sistema consulta vendas e saldo, pede saques e estornos e recebe avisos em tempo real (webhooks) quando um pagamento muda de situação.

As vendas acontecem no checkout da Lastro, pelo link de pagamento de cada produto. Você não precisa coletar dados de cartão: eles nunca passam pelo seu servidor nem pelo da Lastro.

Ambientes

No sandbox nenhum dinheiro de verdade circula. Para simular um cartão use os tokens tok_aprovado, tok_recusado e tok_analise.

Autenticação

Envie a chave de API no cabeçalho Authorization. A chave é gerada pela Lastro e mostrada uma única vez; guardamos só o hash dela. Guarde a sua num cofre de segredos, nunca no código nem no navegador.

curl https://api.lastropay.net.br/v1/saldo \
  -H "Authorization: Bearer lst_live_SUA_CHAVE"

Convenções

• Valores em centavos, sempre inteiros: 29700 = R$ 297,00. Nunca use ponto flutuante para dinheiro.
• Datas em ISO 8601 com fuso (UTC): 2026-10-19T17:42:00.000Z.
• Identificadores têm prefixo: ped_ (pedido), saq_ (saque), lnk_ (link). São aleatórios: não tente deduzir a ordem.
• Campos novos podem aparecer nas respostas sem aviso. Ignore o que não conhece.

Idempotência

Toda operação que move dinheiro (POST /v1/saques) exige o cabeçalho Idempotency-Key: um identificador único por operação, de 8 a 64 caracteres (um UUID v4 é ideal). Se a conexão cair e você reenviar com a mesma chave, recebe a mesma operação de volta, nunca uma segunda.

curl -X POST https://api.lastropay.net.br/v1/saques \
  -H "Authorization: Bearer lst_live_SUA_CHAVE" \
  -H "Idempotency-Key: 3f1c2a9e-8b7d-4c1e-9a52-0d6f4b1e7c33" \
  -H "Content-Type: application/json" \
  -d '{"valor": 50000}'

Erros

Erros devolvem um JSON com uma mensagem que você pode mostrar ao usuário e um código estável para o seu programa:

{ "error": "Saldo disponível insuficiente.", "codigo": "saldo" }

Pedidos

Um pedido nasce quando o comprador paga no checkout. Situações possíveis:

Listar pedidos

Do mais recente para o mais antigo. Para a próxima página, passe em antes_de o criado_em do último item.

[
  {
    "id": "ped_7k2m9x4qa8c3vb6n2p5r",
    "status": "pago",
    "metodo": "pix",
    "total": 28215,
    "parcelas": 1,
    "taxa_lastro": 561,
    "liquido_seller": 27654,
    "reserva": 2765,
    "codigo_lst": "LST-8F3K-Q2MX-7TCV",
    "comprador_nome": "João Pereira",
    "comprador_email": "joao@email.com",
    "criado_em": "2026-10-19T17:40:11.000Z",
    "pago_em": "2026-10-19T17:41:02.000Z",
    "metadados": { "pedido_loja": "1234", "utm_source": "instagram" }
  }
]

Filtre por um metadado com ?metadados.pedido_loja=1234 (valor exato).

Metadados

Guarde no pedido o que você precisa para reconciliar com o seu sistema: id do pedido na loja, UTM, afiliado, plataforma. Eles voltam em GET /v1/pedidos e em todos os webhooks.

• Pelo link: qualquer parâmetro meta_* do link vira metadado. pagar.lastropay.net.br/?l=lnk_…&meta_pedido_loja=1234 grava pedido_loja: "1234". UTMs (utm_source, utm_medium, utm_campaign, utm_content, utm_term), src, sck, ref e afiliado são guardados automaticamente.
• Pela API: envie metadados (ou metadata) ao criar o pedido.

{ "metadados": { "pedido_loja": "1234", "plataforma": "shopify", "itens": 2, "primeira_compra": true } }

Regras: até 30 chaves; chave com letras, números, _, - ou . (até 40); valor texto (até 500), número ou booleano; até 4 KB no total. null descarta a chave.

Tema do checkout

O checkout pode ter a cara da sua marca sem perder o que faz ele converter. O jeito mais fácil é pelo painel, em Personalizar checkout, com prévia ao vivo. Pela API:

{ "cor": "#1F4FD8", "fundo": "claro", "resumo": "cor", "layout": "duas_colunas", "cantos": "suaves",
  "titulo": "Falta pouco para começar", "mensagem": "Acesso liberado no seu e-mail.",
  "garantia_dias": 7, "metodo_inicial": "pix" }

Corpo: a imagem (PNG, JPG ou WebP, até 200 KB). Campos, etapas, selo "Seller verificado", Código LST e textos de segurança não são personalizáveis: são iguais em todos os checkouts.

Estornos

Devolve o valor integral ao comprador (estorno parcial não é suportado). Só vale para pedidos pago. O valor sai do seu saldo; a taxa da transação não é devolvida.

{ "resultado": "aplicado", "status": "estornado" }

Prova de entrega

Informe à Lastro quando o comprador acessou o produto: login na área de membros, aula assistida, download ou envio físico. Cada registro entra no dossiê de defesa e é a prova que mais ganha contestação do tipo "não recebi".

{ "tipo": "acesso_area_membros", "ocorreu_em": "2026-10-19T18:02:11Z",
  "ip": "203.0.113.7", "dispositivo": "Mozilla/5.0 (iPhone…)", "detalhe": "Aula 1 assistida" }

Tipos: acesso_area_membros, download, envio_fisico, outro. O botão "Acessar meu produto" do e-mail da Lastro já registra o primeiro acesso sozinho.

Saldo

{ "disponivel": 248890, "aLiberar": 512300, "reserva": 61200 }

• disponivel: pode ser sacado agora.
• aLiberar: vendas aprovadas aguardando o prazo de liberação (ex.: cartão em D+30).
• reserva: garantia retida para cobrir estornos, chargebacks e MED; volta ao disponível no prazo do seu nível. Veja os Termos de Uso.

Saques

Envia valor (centavos) com Idempotency-Key. O dinheiro vai para a conta bancária cadastrada, sempre no mesmo CPF ou CNPJ da sua conta.

{ "id": "saq_q4z8m2kd7c1xv9b3n6tp", "status": "processando", "valor": 50000, "tarifa": 0,
  "criadoEm": "2026-10-19T18:00:00.000Z", "concluidoEm": null, "motivoFalha": null }

Situações: solicitado → processando → concluido, ou falhou (o valor volta ao saldo).

Código LST

Rota pública, sem chave, usada pela página Verificar pagamento. Devolve só o necessário para reconhecer a compra, nunca dados do comprador. O último caractere do código é um dígito verificador: códigos com erro de digitação recebem 422 sem consultar o banco.

Webhooks

Configure a URL que vai receber os avisos. A resposta traz o segredo para conferir a assinatura; ele aparece uma única vez. Chamar de novo gera um segredo novo, e enviar null desliga.

{ "url": "https://membros.sualoja.com.br/webhooks/lastro" }

Requisitos da URL: HTTPS, porta 443, domínio público (sem IP nem endereço interno). Redirecionamentos não são seguidos.

Cada aviso é um POST com este formato:

{
  "id": "evt_ped_7k2m9x4qa8c3vb6n2p5r_pedido.pago",
  "evento": "pedido.pago",
  "criadoEm": "2026-10-19T17:41:03.120Z",
  "dados": {
    "id": "ped_7k2m9x4qa8c3vb6n2p5r", "status": "pago", "metodo": "pix",
    "total": 28215, "liquido": 27654, "codigoLst": "LST-8F3K-Q2MX-7TCV",
    "produto": { "id": "prd_3m8k2x9q4z7c", "nome": "Curso Fotografia Pro" },
    "comprador": { "nome": "João Pereira", "email": "joao@email.com" },
    "metadados": { "pedido_loja": "1234", "utm_source": "instagram" }
  }
}

• Responda 2xx em até 10 segundos. Faça o trabalho pesado depois (fila).
• Sem 2xx, reenviamos até 10 vezes com espera crescente (1, 2, 4, 8… minutos).
• Um mesmo evento pode chegar mais de uma vez: use o id para não processar em dobro.
• A ordem de chegada não é garantida. Na dúvida, consulte GET /v1/pedidos.

Verificar a assinatura

Todo aviso traz o cabeçalho Lastro-Assinatura: t=1792379548,v1=5d41…, em que v1 é o HMAC-SHA256, em hexadecimal, de t + "." + corpo com o seu segredo. Recuse se a assinatura não bater ou se t tiver mais de 5 minutos.

// Node.js (Express). Use o corpo BRUTO, antes de qualquer JSON.parse.
import crypto from "node:crypto";

app.post("/webhooks/lastro", express.raw({ type: "application/json" }), (req, res) => {
  const cab = req.get("Lastro-Assinatura") || "";
  const t = /t=(\d+)/.exec(cab)?.[1];
  const v1 = /v1=([a-f0-9]{64})/.exec(cab)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(401);

  const esperado = crypto.createHmac("sha256", process.env.LASTRO_WEBHOOK_SEGREDO)
    .update(`${t}.${req.body}`).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))) return res.sendStatus(401);

  const evento = JSON.parse(req.body);
  // registre evento.id para não processar duas vezes; enfileire o trabalho
  res.sendStatus(200);
});

# Python (Flask)
import hmac, hashlib, time, re
from flask import request, abort

@app.post("/webhooks/lastro")
def lastro():
    cab = request.headers.get("Lastro-Assinatura", "")
    t = re.search(r"t=(\d+)", cab); v1 = re.search(r"v1=([a-f0-9]{64})", cab)
    if not t or not v1 or abs(time.time() - int(t[1])) > 300: abort(401)
    esperado = hmac.new(SEGREDO.encode(), f"{t[1]}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperado, v1[1]): abort(401)
    return "", 200

Lista de eventos

Limites

As rotas públicas e o checkout têm limite por IP. Ao receber 429, espere e tente de novo com espera crescente. Integrações de alto volume: fale com a gente antes.

Em breve

• Criar e editar produtos e links de pagamento pela API.
• Consulta de um pedido por id e por externalId do seu sistema.
• Extrato do saldo (cada lançamento) e relatório de conciliação.
• Reenvio manual de webhooks pelo painel.

Dúvidas técnicas: dev@lastropay.net.br.