Manuais de integração — LC Pay API

Fluxos ponta a ponta prontos para copiar. Base HML: https://api-hml.lcpay.com.br.
Todas as chamadas usam Authorization: Bearer <token> e Accept: application/json.

PIX dinâmico com conciliação automática por webhook

Objetivo: cobrar via PIX imediato e ser avisado do pagamento sem polling.

Criar o PIX informando sua URL de callback:

POST /api/v2/movimentacao/{accountId}/pixCashIn
{ "valorTotal": 149.90, "numeroPedido": "PEDIDO-2026-0042",
  "conteudo": "Venda balcão", "urlCallBackIntegrador": "https://seu-sistema.com.br/webhooks/pix" }

Guardar data.transactionId (chave de conciliação) e apresentar ao pagador
data.instantPayment.textContent (copia-e-cola) e/ou generateImage.imageContent (QR base64).

Receber o webhook quando pago — POST na sua URL, corpo vazio, dados nos headers:

webhook-event-type: pix.payment

webhook-transaction-id: <transactionId>

X-Api-Key: <sua chave>

No seu endpoint: validar X-Api-Key, conciliar por webhook-transaction-id,
responder 2xx e processar de forma idempotente (a mesma notificação pode repetir).

Fallback (opcional): se o webhook não chegar, consulte o status:

GET /api/accounts/{accountId}/consultarTransactions/{transactionId}

Considere pago quando transactionStatus == APPROVED.

Sem urlCallBackIntegrador, nenhum webhook é disparado — a conciliação passa a depender do passo 5 (polling).

Cobrança com vencimento + reemissão de PDF

Objetivo: emitir cobrança(s) com vencimento, entregar o PDF e conciliar.

Criar a cobrança:

Parcelas de mesmo valor → POST /api/v2/movimentacao/{accountId}/pixCobranca

Parcelas com valores diferentes → POST /api/v2/movimentacao/{accountId}/pixCobrancaIntegracao

Guardar por parcela: numeroDocumento (para reemitir/inativar) e transactionId/transacaoId (para consultar/conciliar).

Entregar ao pagador o documento.link (PDF) e/ou o copia-e-cola.

Conciliar pelo webhook — no PIX com vencimento o header webhook-external-code traz o codigoExterno da cobrança.

Reemitir o PDF quando necessário:

POST /api/v2/cobranca-cliente-final/{accountId}/reemissao-pix-cobranca
{ "movimentacaoIds": [2440] }        # resposta é BINÁRIA (application/pdf)

Cancelar uma cobrança em aberto:

DELETE /api/v2/cobranca-cliente-final/{numeroDocumento}/inativar

Devolução (refund) de um PIX pago

Descobrir o motivo válido (BACEN):

GET /api/movimentacao/instant-payments/BR/return-codes

Solicitar a devolução (total ou parcial):

POST /api/movimentacao/{accountId}/instant-payments/{transactionId}/returns
{ "externalIdentifier": "<uuid seu>", "amount": 50, "returnReasonCode": "MD06" }

amount menor que o valor pago = devolução parcial.

Use um externalIdentifier estável para garantir idempotência.

Guardar o data.transactionId retornado (id da devolução).

Boas práticas gerais

Idempotência: concilie sempre por transactionId; trate webhooks repetidos.

Erros: o corpo segue { "error": { "code": "<http>", "msg": "..." } }. Trate 4xx como erro da requisição e 5xx como transitório (com retry/alerta).

Ambientes: valide primeiro em HML (api-hml.lcpay.com.br) antes de produção.

Token: gerado no painel LC Pay (menu "Tokens PDV"); validade ~2 anos; trate como senha.

Manuais de integração — LC Pay API

PIX dinâmico com conciliação automática por webhook#

Cobrança com vencimento + reemissão de PDF#

Devolução (refund) de um PIX pago#

Boas práticas gerais#

PIX dinâmico com conciliação automática por webhook

Cobrança com vencimento + reemissão de PDF

Devolução (refund) de um PIX pago

Boas práticas gerais