Criar cobrança via API

O endpoint POST /api/v1/direct/payment cria uma cobrança de forma programática. É o que você usa para gerar um PIX dinâmico a partir de um bot (Typebot), um backend próprio ou um checkout externo.

Autenticação

Envie suas chaves nos headers (veja Autenticação):

lemontech-gateway-publickey: pk_sua_public_key
lemontech-gateway-secretkey: sk_sua_secret_key

Cobrança PIX

curl -X POST https://api.paglemon.com.br/api/v1/direct/payment \
  -H "Content-Type: application/json" \
  -H "lemontech-gateway-publickey: pk_sua_public_key" \
  -H "lemontech-gateway-secretkey: sk_sua_secret_key" \
  -H "Idempotency-Key: pedido-123" \
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "paymentMethod": "pix",
    "description": "Pedido #123",
    "externalRef": "order_123",
    "customer": {
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "11999998888",
      "document": { "number": "12345678909", "type": "cpf" }
    }
  }'

Resposta (201):

{
  "data": {
    "id": "pay_abc123",
    "status": "PENDING",
    "amount": 19.90,
    "currency": "BRL",
    "paymentMethod": "pix",
    "qrCode": "00020126...5204000053039865802BR...6304ABCD",
    "customer": { "id": "cus_1", "name": "Maria Silva", "email": "[email protected]" }
  }
}

• amount é enviado em centavos (1990 = R$ 19,90).
• qrCode é o PIX copia-e-cola — mostre como texto e/ou gere o QR a partir dele.
• O Idempotency-Key (opcional) evita cobrança duplicada em reenvios: a mesma chave replica a resposta anterior.

Cobrança no cartão

Para cartão, envie paymentMethod: "credit_card" e o objeto card (prefira hash/tokenização a dados crus):

{
  "amount": 1990,
  "paymentMethod": "credit_card",
  "installments": 1,
  "customer": { "...": "..." },
  "card": { "hash": "tok_gerado_no_client" }
}

A resposta traz clientSecret (para finalizar via hosted-fields do gateway) e status: "PENDING".

Status do pagamento

Como sei que foi pago? O caminho recomendado é o Webhook: você recebe o evento payment.approved no instante da confirmação, sem precisar ficar perguntando. Se preferir um destino só para aquela cobrança, envie postbackUrl no corpo dela.

Consultar o status por API

Quando precisar conferir o estado de uma cobrança — para reconciliar, ou porque seu servidor perdeu o webhook — use:

GET https://api.paglemon.com.br/api/v1/payments/{id}

Onde {id} é o id devolvido na criação da cobrança.

Este endpoint é público: não envie Authorization, nem as chaves lemontech-gateway-publickey / lemontech-gateway-secretkey. Como ele não exige credencial, a resposta vem reduzida ao essencial — sem CPF, telefone, endereço do comprador ou valores de taxa:

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": "FINISHED",
  "method": "pix",
  "amount": 61.90,
  "currency": "BRL",
  "createdAt": "2026-08-19T03:15:22.000Z",
  "expiresAt": "2026-08-20T03:15:22.000Z",
  "confirmedAt": "2026-08-19T03:16:04.000Z"
}

status: "FINISHED" significa pago (veja a tabela acima), e confirmedAt traz o momento da confirmação.

⚠️

Não use consulta no lugar do webhook. Conferir um pedido específico ou reconciliar o dia é o uso correto. Já ficar consultando todas as cobranças em intervalo curto (polling) gera carga à toa e ainda te avisa depois do que o webhook avisaria.

🛑

Não existe GET /api/v1/direct/payment/{id}. O /api/v1/direct/payment aceita apenas POST, para criar a cobrança. Um GET nesse caminho responde 401, porque a checagem de chave de API roda antes de o roteador concluir que a rota não existe — o erro fala em credencial, mas o problema é o endereço. Para consultar, use GET /api/v1/payments/{id} acima.

Campos úteis do corpo

• externalRef — seu identificador do pedido (volta nos eventos).
• postbackUrl — URL que recebe o evento deste pagamento (sobrepõe os webhooks da conta).
• metadata — dados livres (string ou objeto).
• items, shipping — detalhamento opcional do pedido.
• ip — IP do comprador. Como a chamada sai do seu servidor, sem este campo o único IP que temos é o da sua máquina: o antifraude do adquirente perde sinal e o mapa de vendas fica sem a localização da compra. Envie o IP que o navegador do comprador usou no seu checkout.