ld bankDocumentação

Receba por Pix com uma API

Crie uma cobrança, mostre o QR code para o seu cliente e receba um webhook quando ela for paga. A API é REST, recebe e devolve JSON e usa códigos HTTP comuns.

Endereço base
https://ldpagamentos.com/v1
Autenticação
Chave secreta no header Authorization
Valores
Sempre em centavos inteiros: 19750 = R$ 197,50
Datas
ISO 8601 com fuso horário

Início rápido

  1. Crie sua conta e entre no painel. O ambiente de teste já vem liberado.
  2. Gere uma chave de teste em Desenvolvedor → Chaves de API. Ela começa com sk_test_ e aparece uma única vez.
  3. Crie uma cobrança com o exemplo ao lado e mostre o pix.qr_code para o cliente, como QR code ou copia e cola.
  4. Cadastre um webhook para saber quando ela for paga, sem ficar consultando.
  5. Simule o pagamento no ambiente de teste. Quando tudo funcionar, peça a liberação da produção e troque a chave por uma sk_live_.
curl https://ldpagamentos.com/v1/charges \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-77" \
  -d '{
    "amount": 19750,
    "description": "Pedido 77",
    "items": [{ "name": "Camiseta Básica", "quantity": 1, "unit_amount": 19750, "sku": "CAM-01" }],
    "customer": {
      "name": "Ana Silva",
      "email": "[email protected]",
      "document": "52998224725",
      "phone": "11999998888"
    }
  }'

Autenticação

Envie a chave secreta em todas as requisições, no header Authorization: Bearer. Requisição sem chave, com chave inválida ou revogada recebe 401.

A chave dá acesso ao dinheiro da sua conta. Use-a só no seu servidor: nunca no aplicativo, no navegador ou em um repositório de código. Se ela vazar, revogue no painel e gere outra.

Permissões da chave

Cada chave tem escopos. Uma chave sem o escopo necessário recebe 403. Dê a cada sistema só o que ele precisa.

EscopoPermite
charges:read · charges:writeConsultar e criar ou cancelar cobranças
refunds:read · refunds:writeConsultar e criar estornos
balance:readConsultar saldo e taxas
webhooks:read · webhooks:writeGerenciar endpoints de webhook
events:readConsultar o histórico de eventos
Authorization: Bearer sk_live_sua_chave

Teste e produção

O prefixo da chave define o ambiente. Com sk_test_ nada é cobrado de verdade e você pode simular pagamentos. Com sk_live_ as cobranças são reais.

Os dois ambientes são separados: uma cobrança criada em teste não aparece em produção, e cada um tem seus próprios webhooks. A produção é liberada depois da análise do cadastro.

Idempotência

Todo POST exige o header Idempotency-Key com um valor único por operação, como o número do seu pedido. Se a conexão cair e você repetir a requisição com a mesma chave, recebe a mesma resposta em vez de criar uma segunda cobrança.

  • A resposta repetida vem com o header Idempotent-Replayed: true.
  • Reusar a chave com um corpo diferente devolve 409 idempotency_key_reused.
  • A chave vale por 24 horas e pode ter até 255 caracteres.
Idempotency-Key: pedido-77-tentativa-1

Erros

Erros sempre vêm no mesmo formato. Use o code para decidir o que fazer no seu sistema e guarde o request_id: com ele o suporte encontra a requisição.

HTTPQuando acontece
400JSON inválido ou header obrigatório ausente
401Chave ausente, inválida ou revogada
403Chave sem o escopo, ambiente não liberado ou conta bloqueada
404Recurso não existe ou é de outro ambiente
409Conflito de idempotência ou cobrança em um estado que não permite a ação
422Algum campo inválido. O param diz qual
429Limite de requisições excedido
5xxFalha temporária. Repita com a mesma Idempotency-Key
{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "param": "customer.document",
    "message": "CPF ou CNPJ inválido",
    "request_id": "req_4f1c2a9e7b0d3c5a8e61"
  }
}

Limites

Cada chave pode fazer até 600 requisições por minuto. Acima disso a API responde 429: espere alguns segundos e tente de novo, de preferência com intervalo crescente entre as tentativas.

Em produção toda conta nasce com limite de R$ 1.000,00 por cobrança; conforme o histórico, nossa equipe aumenta (ou remove) esse limite, e pode definir também um volume máximo por dia. Cobrança acima do limite responde 422 com amount_above_limit (a mensagem informa o limite atual) ou daily_limit_reached. Em teste não há limite.

O objeto cobrança

Uma cobrança representa um pagamento Pix. Ela nasce pending com o código Pix pronto e muda de status quando o cliente paga ou quando o prazo acaba.

StatusSignificado
pendingPix gerado, esperando o pagamento
paidPago. O valor líquido entra no seu saldo
expiredO prazo acabou sem pagamento
canceledCancelada antes de ser paga
failedNão foi possível gerar o Pix
partially_refunded · refundedParte ou todo o valor foi devolvido
chargedbackO pagador contestou no banco e o valor foi devolvido a ele. Sai do seu saldo

fee é a taxa e net é o que entra no seu saldo. O documento do cliente sempre volta mascarado.

{
  "object": "charge",
  "id": "ch_8F2KQ7XW4Mb1cD9eFgH0iJ",
  "environment": "live",
  "status": "pending",
  "method": "pix",
  "amount": 19750,
  "currency": "BRL",
  "fee": 1088,
  "net": 18662,
  "refunded_amount": 0,
  "customer": {
    "name": "Ana Silva",
    "email": "[email protected]",
    "document": "*******4725"
  },
  "description": "Pedido 77",
  "items": [{ "name": "Camiseta Básica", "quantity": 1, "unit_amount": 19750, "sku": "CAM-01" }],
  "seller": null,
  "metadata": { "pedido": "77" },
  "pix": {
    "qr_code": "00020101021226880014br.gov.bcb.pix…",
    "qr_code_url": null,
    "expires_at": "2026-09-21T15:32:00.000-03:00"
  },
  "paid_at": null,
  "created_at": "2026-09-21T14:32:00.000-03:00",
  "refunds": []
}

POST /v1/charges

Cria uma cobrança Pix. A resposta já traz o pix.qr_code: mostre como QR code ou como texto para o cliente copiar.

CampoDescrição
amountobrigatórioValor em centavos. Mínimo 100 (R$ 1,00)
customerobrigatórioname, email, document (CPF ou CNPJ, só números) e phone (com DDD)
descriptionAparece para o cliente e fica guardada na cobrança. Até 250 caracteres. Se não vier, usamos o nome do primeiro item
itemsOpcional. Lista de produtos: name (obrigatório), quantity (padrão 1), unit_amount em centavos e sku. Até 20 itens. Aparecem no painel e voltam na cobrança
expires_inValidade do Pix em segundos, de 60 a 604800. Padrão: 3600
metadataAté 20 chaves suas, como o número do pedido. Volta na cobrança e nos webhooks
sellerid e name de quem vendeu, se você tiver vários vendedores. Agrupa as vendas no painel
curl https://ldpagamentos.com/v1/charges \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-77" \
  -d '{
    "amount": 19750,
    "description": "Pedido 77",
    "items": [{ "name": "Camiseta Básica", "quantity": 1, "unit_amount": 19750, "sku": "CAM-01" }],
    "expires_in": 3600,
    "customer": {
      "name": "Ana Silva",
      "email": "[email protected]",
      "document": "52998224725",
      "phone": "11999998888"
    },
    "metadata": { "pedido": "77" }
  }'

GET /v1/charges/{id}

Devolve a cobrança com o status atual e os estornos feitos. Use para confirmar um pagamento recebido por webhook antes de liberar um pedido de valor alto.

curl https://ldpagamentos.com/v1/charges/ch_8F2KQ7XW4Mb1cD9eFgH0iJ \
  -H "Authorization: Bearer $API_KEY"

GET /v1/charges

Lista as cobranças da mais nova para a mais antiga.

ParâmetroDescrição
statusFiltra por status, por exemplo paid
limitDe 1 a 100. Padrão: 20
starting_afterPara a próxima página, envie o next_cursor da resposta anterior
curl "https://ldpagamentos.com/v1/charges?status=paid&limit=50" \
  -H "Authorization: Bearer $API_KEY"
{
  "object": "list",
  "data": [ { "object": "charge", "id": "ch_…", … } ],
  "has_more": true,
  "next_cursor": "ch_…"
}

POST /v1/charges/{id}/cancel

Cancela uma cobrança pending para que o Pix não possa mais ser pago. Se ela já tiver sido paga, a resposta é 409 charge_already_paid e a cobrança passa a constar como paga.

curl -X POST https://ldpagamentos.com/v1/charges/ch_8F2KQ7XW4Mb1cD9eFgH0iJ/cancel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: cancelar-pedido-77"

POST /v1/refunds

Devolve o valor de uma cobrança paga, total ou parcial. Sem amount, devolve tudo o que ainda não foi estornado. O valor sai do seu saldo disponível.

O estorno pode ficar pending por alguns instantes. O resultado final chega pelos eventos refund.succeeded ou refund.failed. Consulte com GET /v1/refunds/{id}.

curl https://ldpagamentos.com/v1/refunds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: estorno-pedido-77" \
  -d '{ "charge_id": "ch_8F2KQ7XW4Mb1cD9eFgH0iJ", "amount": 5000, "reason": "cliente desistiu" }'

GET /v1/balance e /v1/fees

available é o que você pode sacar, reserved é a reserva financeira (uma parte de cada venda que fica retida por alguns dias e volta sozinha) e payouts_total é o total já enviado para saque. /v1/fees mostra a taxa do seu plano e um exemplo de cálculo.

{
  "object": "balance",
  "environment": "live",
  "currency": "BRL",
  "available": 123450,
  "pending": 0,
  "reserved": 0,
  "payouts_total": 500000
}

Webhooks

Quando algo muda, avisamos o seu sistema com um POST no endereço que você cadastrar. Cadastre pelo painel ou pela API. O endereço precisa ser https e público.

A criação devolve o secret uma única vez. Guarde-o: ele assina cada entrega e é diferente da sua chave de API.

Outras rotas: GET /v1/webhook_endpoints, DELETE /v1/webhook_endpoints/{id}, POST …/{id}/rotate_secret e POST …/{id}/test, que envia um test.ping.

curl https://ldpagamentos.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-1" \
  -d '{
    "url": "https://sualoja.com.br/webhooks/pagamentos",
    "events": ["charge.paid", "charge.expired", "refund.succeeded"]
  }'

Eventos

Cada entrega traz um evento com o tipo e os dados do objeto. O mesmo evento pode chegar mais de uma vez: use o id para não processar duas vezes.

EventoQuando
charge.paidO cliente pagou. É o evento para liberar o pedido
charge.pendingO Pix foi gerado
charge.expired · charge.canceledA cobrança não pode mais ser paga
charge.failedNão foi possível gerar o Pix
refund.succeeded · refund.failedResultado de um estorno
charge.chargedbackContestação confirmada pelo banco. O valor sai do seu saldo
payout.paidUm saque seu foi pago
test.pingEnvio de teste

O histórico fica em GET /v1/events.

{
  "id": "evt_3kQ9wZ1pLm7Vx2Cn8Rt4Yb",
  "type": "charge.paid",
  "environment": "live",
  "created_at": "2026-09-21T17:32:05+00:00",
  "data": {
    "id": "ch_8F2KQ7XW4Mb1cD9eFgH0iJ",
    "amount": 19750,
    "fee": 1088,
    "net": 18662,
    "status": "paid"
  }
}

Verificar a assinatura

Confira toda entrega antes de confiar nela. O header X-Signature tem o formato t=<timestamp>,v1=<assinatura>.

  1. Calcule o HMAC-SHA256 de timestamp + "." + corpo com o secret do endpoint. Use o corpo bruto, exatamente como chegou, antes de converter o JSON.
  2. Compare com o v1 usando comparação em tempo constante.
  3. Recuse se o timestamp tiver mais de 5 minutos de diferença do seu relógio. Isso impede que alguém reenvie uma entrega antiga.

Cada entrega também traz X-Event-Id, X-Event-Type e X-Delivery-Attempt.

$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET');

if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $m)
    || abs(time() - (int)$m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
if ($event['type'] === 'charge.paid') {
    // libere o pedido de $event['data']['id'] (uma única vez por $event['id'])
}
http_response_code(200);

Entregas e retentativas

Responda com qualquer status 2xx em até 10 segundos. Se o seu servidor falhar ou demorar, tentamos de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas, 24 horas e mais 24 horas: 8 tentativas no total.

Depois de 50 falhas seguidas o endpoint é desativado. No painel você vê cada entrega, reenvia as que falharam e cadastra o endpoint de novo quando ele voltar.

Responda rápido e faça o trabalho pesado depois, em uma fila. A ordem de chegada dos eventos não é garantida: confira o status atual com GET /v1/charges/{id} se a ordem importar.

Ambiente de teste

Com uma chave sk_test_, simule o pagamento de uma cobrança pendente. Ela passa para paid e o webhook charge.paid é enviado como aconteceria em produção.

Os dois últimos dígitos do valor escolhem o que acontece, para você testar os casos de erro:

Valor termina emResultado
…02Cobrança recusada
…03Pix gerado que nunca é pago
…04Demora na resposta
…05Erro temporário do sistema de pagamento
…06Cobrança normal, mas o estorno falha
outrosTudo funciona normalmente

Links de pagamento criados no ambiente de teste mostram o botão “Simular pagamento aprovado” na tela do Pix.

curl -X POST https://ldpagamentos.com/v1/sandbox/charges/ch_8F2KQ7XW4Mb1cD9eFgH0iJ/pay \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Idempotency-Key: simular-1"