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
- Crie sua conta e entre no painel. O ambiente de teste já vem liberado.
- Gere uma chave de teste em Desenvolvedor → Chaves de API. Ela começa com
sk_test_e aparece uma única vez. - Crie uma cobrança com o exemplo ao lado e mostre o
pix.qr_codepara o cliente, como QR code ou copia e cola. - Cadastre um webhook para saber quando ela for paga, sem ficar consultando.
- 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.
| Escopo | Permite |
|---|---|
charges:read · charges:write | Consultar e criar ou cancelar cobranças |
refunds:read · refunds:write | Consultar e criar estornos |
balance:read | Consultar saldo e taxas |
webhooks:read · webhooks:write | Gerenciar endpoints de webhook |
events:read | Consultar o histórico de eventos |
Authorization: Bearer sk_live_sua_chaveTeste 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-1Erros
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.
| HTTP | Quando acontece |
|---|---|
400 | JSON inválido ou header obrigatório ausente |
401 | Chave ausente, inválida ou revogada |
403 | Chave sem o escopo, ambiente não liberado ou conta bloqueada |
404 | Recurso não existe ou é de outro ambiente |
409 | Conflito de idempotência ou cobrança em um estado que não permite a ação |
422 | Algum campo inválido. O param diz qual |
429 | Limite de requisições excedido |
5xx | Falha 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.
| Status | Significado |
|---|---|
pending | Pix gerado, esperando o pagamento |
paid | Pago. O valor líquido entra no seu saldo |
expired | O prazo acabou sem pagamento |
canceled | Cancelada antes de ser paga |
failed | Não foi possível gerar o Pix |
partially_refunded · refunded | Parte ou todo o valor foi devolvido |
chargedback | O 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.
| Campo | Descrição |
|---|---|
amountobrigatório | Valor em centavos. Mínimo 100 (R$ 1,00) |
customerobrigatório | name, email, document (CPF ou CNPJ, só números) e phone (com DDD) |
description | Aparece para o cliente e fica guardada na cobrança. Até 250 caracteres. Se não vier, usamos o nome do primeiro item |
items | Opcional. 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_in | Validade do Pix em segundos, de 60 a 604800. Padrão: 3600 |
metadata | Até 20 chaves suas, como o número do pedido. Volta na cobrança e nos webhooks |
seller | id 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" }
}'$ch = curl_init('https://ldpagamentos.com/v1/charges');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: pedido-77',
],
CURLOPT_POSTFIELDS => json_encode([
'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',
],
'metadata' => ['pedido' => '77'],
]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge['pix']['qr_code'];const res = await fetch('https://ldpagamentos.com/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido-77',
},
body: JSON.stringify({
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',
},
metadata: { pedido: '77' },
}),
});
const charge = await res.json();
console.log(charge.pix.qr_code);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âmetro | Descrição |
|---|---|
status | Filtra por status, por exemplo paid |
limit | De 1 a 100. Padrão: 20 |
starting_after | Para 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
}Links de pagamento
Para receber sem escrever código, crie um link no painel em Cobrar → Links de pagamento e compartilhe por WhatsApp, redes sociais ou e-mail. O cliente abre uma página de pagamento pronta, preenche os dados e paga com Pix.
- Valor fixo ou definido pelo cliente, com mínimo e máximo.
- Desconto opcional para quem paga com Pix, validade e limite de pagamentos.
- Endereço de retorno para mandar o cliente de volta à sua loja depois de pagar.
Cada pagamento vira uma cobrança comum: aparece na API e no painel, entra no saldo com as mesmas taxas e dispara os mesmos webhooks. Para saber de qual link veio, leia metadata.payment_link.
https://ldpagamentos.com/pay/seu-produto-a1b2c3{
"payment_link": "pl_1EGQ5svIBiR6eirON3c3XN",
"link_price": 49700,
"pix_discount": 2485
}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.
| Evento | Quando |
|---|---|
charge.paid | O cliente pagou. É o evento para liberar o pedido |
charge.pending | O Pix foi gerado |
charge.expired · charge.canceled | A cobrança não pode mais ser paga |
charge.failed | Não foi possível gerar o Pix |
refund.succeeded · refund.failed | Resultado de um estorno |
charge.chargedback | Contestação confirmada pelo banco. O valor sai do seu saldo |
payout.paid | Um saque seu foi pago |
test.ping | Envio 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>.
- Calcule o HMAC-SHA256 de
timestamp + "." + corpocom osecretdo endpoint. Use o corpo bruto, exatamente como chegou, antes de converter o JSON. - Compare com o
v1usando comparação em tempo constante. - 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);const crypto = require('crypto');
app.post('/webhooks/pagamentos', express.raw({ type: 'application/json' }), (req, res) => {
const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(req.get('X-Signature') || '');
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.sendStatus(400);
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(m[1] + '.' + req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))) return res.sendStatus(400);
const event = JSON.parse(req.body);
if (event.type === 'charge.paid') {
// libere o pedido de event.data.id (uma única vez por event.id)
}
res.sendStatus(200);
});import hashlib, hmac, os, time
from flask import request, abort
@app.post('/webhooks/pagamentos')
def webhook():
body = request.get_data()
try:
parts = dict(p.split('=', 1) for p in request.headers.get('X-Signature', '').split(','))
ts, sig = parts['t'], parts['v1']
except (ValueError, KeyError):
abort(400)
if abs(time.time() - int(ts)) > 300:
abort(400)
expected = hmac.new(os.environ['WEBHOOK_SECRET'].encode(), ts.encode() + b'.' + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig):
abort(400)
event = request.get_json()
if event['type'] == 'charge.paid':
pass # libere o pedido de event['data']['id'] (uma única vez por event['id'])
return '', 200Entregas 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 em | Resultado |
|---|---|
…02 | Cobrança recusada |
…03 | Pix gerado que nunca é pago |
…04 | Demora na resposta |
…05 | Erro temporário do sistema de pagamento |
…06 | Cobrança normal, mas o estorno falha |
| outros | Tudo 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"