Fluxos de Integração — Emissão de Pagamentos (PIX) - LC Pay API

Guia prático para emitir pagamentos PIX pela API LC Pay: PIX imediato (dinâmico)
e cobranças com vencimento. Cobre desde a autenticação até a conciliação do
pagamento.

Base URL (Produção): https://api.lcpay.com.br

Base URL (Homologação): https://api-hml.lcpay.com.br

Autenticação: Authorization: Bearer <token> em toda requisição

Headers: Accept: application/json sempre; Content-Type: application/json quando houver corpo

Valide primeiro em Homologação antes de ir para Produção.

Pré-requisitos

Conta LC Pay ativa e o accountId da conta (aparece no portal do cliente).

Token de integração, gerado no painel: menu "Tokens PDV" → informe um nome → Adicionar → copie o token. Validade ~2 anos; trate como senha.

URL de callback (opcional, recomendado): um endpoint HTTPS público no seu sistema para receber a notificação de pagamento (webhook). Sem ele, a confirmação depende de consulta manual (polling).

Qual endpoint usar?

Preciso…	Endpoint	Observação
Cobrar na hora (balcão, PDV, checkout)	PIX Dinâmico `pixCashIn`	Sem vencimento; QR imediato
Emitir cobrança com vencimento, parcelas de mesmo valor	PIX Cobrança `pixCobranca`	Juros/multa, carnê, PDF
Emitir cobrança com valores diferentes por parcela	PIX Cobrança Integração `pixCobrancaIntegracao`	`dadosCobranca` é uma lista

Enums usados nas cobranças:

frequenciaCobranca: MENSAL | SEMANAL (apenas na pixCobranca)

tipoMulta: PERCENTUAL | FIXO

tipoJuros (apenas na pixCobrancaIntegracao): PERCENTUAL_DIA_DIAS_CORRIDOS | PERCENTUAL_MES_DIAS_UTEIS

Visão geral do fluxo

Fluxo 1 — PIX Dinâmico (imediato)

Cobrança na hora, sem vencimento. Retorna QR Code e copia-e-cola.

1.1 Criar

POST /api/v2/movimentacao/{accountId}/pixCashIn

Campo	Tipo	Obrigatório	Regra
`valorTotal`	number	sim	Valor em reais (> 0)
`numeroPedido`	string	sim	Identificador do pedido no seu sistema
`conteudo`	string	sim	Descrição
`urlCallBackIntegrador`	string	não	URL HTTPS de callback (webhook). Vazio = sem notificação

1.2 Resposta (200)

{
  "data": {
    "transactionId": "E37CFF03-76F2-102A-9F42-C58AA360804F",
    "financialStatement": { "status": "CREATED" },
    "totalAmount": 149.90,
    "instantPayment": {
      "textContent": "00020101021226990014br.gov.bcb.pix...6304C290",
      "qrcodeURL": "https://pix-h.bpp.com.br/...",
      "generateImage": { "imageContent": "iVBORw0KGgo... (base64 PNG)", "mimeType": "image/png" },
      "dynamicQrCodeType": "IMMEDIATE"
    }
  }
}

1.3 O que fazer

Guarde data.transactionId (chave de conciliação).

Apresente ao pagador instantPayment.textContent (copia-e-cola) e/ou generateImage.imageContent (QR em base64 PNG).

Aguarde o webhook de pagamento (ver Conciliação).

Atenção: este endpoint não aplica validação de campos (Bean Validation). Envie os dados corretos — valores malformados tendem a retornar 500 em vez de 400.

Fluxo 2 — PIX Cobrança (com vencimento)

Cobrança com data de vencimento, juros/multa e dados do pagador. valorTotal é
o mesmo em todas as parcelas. Gera QR Code e link de PDF.

2.1 Criar

POST /api/v2/movimentacao/{accountId}/pixCobranca

Estrutura do corpo (campos obrigatórios marcados com *):

dadosCobranca * — { valorTotal* (≥ 0.01), dataVencimento* (hoje ou futuro), codigoExterno (máx 100), conteudo (máx 90) }

pagador * — obrigatórios: cpfCnpj* (CPF 11 ou CNPJ 14 válido), nomeFantasia*, nomePagador* (máx 100), cidade* (máx 80). Opcionais: razaoSocial, segmento, email, telefoneCelular, logradouro (máx 150), bairro, uf (2 letras maiúsculas se enviado), cep (8 dígitos se enviado)

regrasCobranca * —

{ juros* (≥ 0), multa* (≥ 0), frequenciaCobranca (MENSAL|SEMANAL), tipoMulta (PERCENTUAL|FIXO), quantidadeParcelas* (1 a 12) }

urlCallBack * — URL HTTPS de callback (webhook)

2.2 Resposta (200)

Retorna uma lista — um item por parcela.

[
  {
    "reciboPagador": {
      "numeroDocumento": 2440,
      "vencimento": "2026-02-20",
      "valor": 55,
      "numeroParcela": 1,
      "totalParcelas": 1
    },
    "pagamentoPix": {
      "transacaoId": "6A5A7118-D74A-18A6-1FE7-B7105FAEE5A6",
      "numeroDocumento": 2440,
      "documento": { "link": "https://api-hml.lcpay.com.br/api/v2/movimentacao/download/inv_47acb34a.pdf" }
    }
  }
]

2.3 O que fazer

Guarde por parcela: numeroDocumento (para reemitir PDF ou inativar) e transacaoId (para consultar/conciliar).

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

Validação ativa (Bean Validation): campo inválido retorna 400 com a primeira violação (ex.: cpfCnpj: CPF ou CNPJ inválido).

Fluxo 3 — PIX Cobrança Integração (parcelas com valores diferentes)

Igual à cobrança, mas dadosCobranca é uma lista (cada parcela com seu
valor/vencimento) e regrasCobranca usa tipoJuros (sem frequenciaCobranca
nem quantidadeParcelas).

3.1 Criar

POST /api/v2/movimentacao/{accountId}/pixCobrancaIntegracao

3.2 Resposta (201)

data.transactions é uma lista — um item por parcela, cada um com
instantPayment (copia-e-cola/QR) e cobranca (numeroDocumento para reemissão).

{
  "data": {
    "transactions": [
      {
        "transactionId": "DE76B718-659F-CE2B-0E5F-F427548CE027",
        "financialStatement": { "status": "CREATED" },
        "instantPayment": { "textContent": "000201...63048DA7", "dynamicQrCodeType": "BILLING_DUE_DATE" },
        "cobranca": { "numeroDocumento": 2476, "vencimento": "2026-02-20", "valor": 55, "numeroParcela": 1, "totalParcelas": 2 }
      }
    ]
  }
}

Conciliação do pagamento

Após emitir, você sabe que foi pago de duas formas:

Webhook (recomendado)

Ao ser pago, o LC Pay faz um POST na sua URL de callback. Corpo vazio — os
dados vão nos headers:

Header	Descrição
`webhook-event-type`	`pix.payment`
`webhook-transaction-id`	`transactionId` — chave de conciliação
`webhook-external-code`	`codigoExterno` da cobrança (vazio no PIX dinâmico)
`X-Api-Key`	Chave de autenticação — valide antes de processar

Regras:

Responda HTTP 2xx rapidamente; processe o pesado de forma assíncrona.

Trate de forma idempotente por webhook-transaction-id (a mesma notificação pode repetir).

Em falha (não-2xx/timeout), o LC Pay reenvia ~a cada 2 minutos, até ~30 tentativas.

Consulta de status (fallback)

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

transactionStatus possíveis: CREATED (aguardando), APPROVED (pago),
REJECTED, OPEN, CANCELED, PARTIAL, UNFINISHED.
Considere pago apenas quando APPROVED.

Depois da emissão

Ação	Endpoint
Reemitir o PDF da cobrança	`POST /api/v2/cobranca-cliente-final/{accountId}/reemissao-pix-cobranca` — corpo `{ "movimentacaoIds": [numeroDocumento] }` (resposta binária `application/pdf`)
Inativar uma cobrança em aberto	`DELETE /api/v2/cobranca-cliente-final/{numeroDocumento}/inativar`
Devolver (refund) um PIX pago	`POST /api/movimentacao/{accountId}/instant-payments/{transactionId}/returns`

Erros comuns na emissão

Formato padrão: { "error": { "code": "<http>", "msg": "<mensagem>" } }

HTTP	Quando ocorre
400	Campo inválido (cobranças, via Bean Validation) — retorna a primeira violação
401	Token ausente, expirado ou inválido
403	Token sem permissão sobre a conta (`accountId`)
404	`accountId` não encontrado
422	Violação de regra de negócio (operação inválida no estado atual)
500	Erro interno ou payload malformado no PIX dinâmico (sem Bean Validation)

Documentos relacionados: receitas-integracao.md (receitas ponta a ponta),
openapi.yaml (contrato completo), a página de Webhook na documentação pública.

Fluxos de Integração — Emissão de Pagamentos (PIX)

Pré-requisitos#

Qual endpoint usar?#

Visão geral do fluxo#

Fluxo 1 — PIX Dinâmico (imediato)#

1.1 Criar#

1.2 Resposta (200)#

1.3 O que fazer#

Fluxo 2 — PIX Cobrança (com vencimento)#

2.1 Criar#

2.2 Resposta (200)#

2.3 O que fazer#

Fluxo 3 — PIX Cobrança Integração (parcelas com valores diferentes)#

3.1 Criar#

3.2 Resposta (201)#

Conciliação do pagamento#

Webhook (recomendado)#

Consulta de status (fallback)#

Depois da emissão#

Erros comuns na emissão#