Quickstart

Em cinco minutos você cria uma cobrança PIX no ambiente de teste, vê o QR Code e recebe o evento transaction.paid. Nada de dinheiro se move e nenhum SDK é instalado.

1. Pegue uma chave de teste

A chave nasce no painel. Escolha o ambiente de teste: a chave sai com o prefixo sk_test_ e funciona antes mesmo de o seu KYC ser aprovado.

O segredo aparece uma única vez, na criação. Guarde em variável de ambiente, nunca no repositório e nunca no front:

export LM_API_URL=https://api.leztypay.com
export LM_API_KEY=sk_test_sua_chave_aqui

2. Crie a primeira cobrança

amount é sempre inteiro em centavos: 10000 são cem reais. O header Idempotency-Key é obrigatório e é você quem escolhe o valor, normalmente o id do pedido na sua loja.

Copiar#!/usr/bin/env bash
# Cria uma cobrança PIX. Precisa de LM_API_URL e LM_API_KEY no ambiente.
#   export LM_API_URL=https://api.leztypay.com
#   export LM_API_KEY=sk_test_...
set -euo pipefail

curl --fail-with-body -sS "$LM_API_URL/v1/transactions" \
  -H "Authorization: Bearer $LM_API_KEY" \
  -H "Idempotency-Key: pedido-A123-tentativa-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payment_method": "pix",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "document": "123.456.789-09"
    },
    "items": [{ "name": "Curso X", "quantity": 1, "unit_amount": 10000 }],
    "pix": { "expires_in_seconds": 1800 },
    "postback_url": "https://loja.exemplo.com/webhooks/leztypay",
    "metadata": { "order_id": "A123" }
  }'

A resposta 201 traz pix.payload (o copia e cola) e pix.qr_base64 (a imagem PNG já em base64). Mostre um dos dois ao cliente. Em Node, sem dependência nenhuma:

Copiar// Cria uma cobrança PIX com o fetch global do Node 22. Sem dependência.
//   LM_API_URL=https://api.leztypay.com LM_API_KEY=sk_test_... node create-transaction.mjs
const apiUrl = process.env.LM_API_URL;
const apiKey = process.env.LM_API_KEY;

// A chave de idempotência é do SEU pedido, não da requisição. Repetir a mesma chave com o
// mesmo corpo devolve a cobrança já criada em vez de criar uma segunda.
const idempotencyKey = 'pedido-A123-tentativa-1';

const res = await fetch(`${apiUrl}/v1/transactions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000,
    payment_method: 'pix',
    customer: {
      name: 'Maria Silva',
      email: 'maria@exemplo.com',
      document: '123.456.789-09',
    },
    items: [{ name: 'Curso X', quantity: 1, unit_amount: 10000 }],
    pix: { expires_in_seconds: 1800 },
    postback_url: 'https://loja.exemplo.com/webhooks/leztypay',
    metadata: { order_id: 'A123' },
  }),
});

const body = await res.json();

if (!res.ok) {
  // Todo erro tem o mesmo envelope. `request_id` é o que o suporte pede.
  console.error(res.status, body.error.code, body.error.message, body.error.request_id);
  process.exit(1);
}

if (res.headers.get('Idempotent-Replayed') === 'true') {
  console.log('resposta salva de uma tentativa anterior com a mesma chave');
}

console.log('id:', body.id);
console.log('status:', body.status);
console.log('expira em:', body.pix.expires_at);
console.log('copia e cola:', body.pix.payload);

3. Faça a cobrança ser paga

No ambiente de teste ninguém abre o app do banco. Quem decide o desfecho é você, pelos dois últimos dígitos de amount. Um valor terminado em qualquer coisa fora da lista de gatilhos, como os 10000 acima, é pago sozinho poucos segundos depois da criação.

Terminando em 01 a cobrança nunca paga e expira. Terminando em 03 a criação já volta recusada. A lista inteira está em Gatilhos do ambiente de teste.

4. Receba o webhook

Quando a cobrança é paga, a LeztyPay entrega o evento transaction.paid assinado no seu endpoint. Duas formas de apontar o destino:

• postback_url na cobrança, como no exemplo acima. Vale só para aquela cobrança e é o caminho mais rápido para testar.
• Endpoint da conta, cadastrado no painel. Recebe todos os eventos, tem segredo próprio e é o que você usa em produção.

O endpoint precisa responder 2xx rápido e verificar a assinatura antes de confiar no corpo. Como fazer isso está em Webhooks.

5. Confirme pelo GET

Webhook é aviso, não é fonte de verdade. A qualquer momento consulte a cobrança pelo id e confira status e paid_at:

Copiar#!/usr/bin/env bash
# Consulta uma cobrança pelo id. O GET é sempre a fonte de verdade do status.
#   LM_TRANSACTION_ID=txn_01j... ./get-transaction.sh
set -euo pipefail

curl --fail-with-body -sS "$LM_API_URL/v1/transactions/$LM_TRANSACTION_ID" \
  -H "Authorization: Bearer $LM_API_KEY"

Próximo passo

Entenda a chave que você acabou de usar em Autenticação, e depois Criar uma cobrança para os campos que ficaram de fora deste roteiro.

Referência da operação: Cria uma cobrança PIX.