# LC Pay API — Integração PIX (v2.0)

> API de integração PIX do LC Pay: criação de PIX dinâmico e cobranças com
> vencimento, consulta de status, devolução (refund) e reemissão de PDF. A
> notificação de pagamento é entregue por webhook (veja a seção WEBHOOK).

Contato: Equipe LC Pay — https://doc-api.lcpay.com.br

## Servidores
- Produção:   https://api.lcpay.com.br
- Homologação: https://api-hml.lcpay.com.br

## Autenticação
Todas as chamadas usam Bearer Token (JWT) no header `Authorization: Bearer <token>`.
O token de integração do cliente é gerado no painel, menu "Tokens PDV".

## Formato de erro padrão (todos os endpoints)
```json
{ "error": { "code": "<http>", "msg": "<mensagem>" } }
```
- `code`: código HTTP como string (ex: "409")
- `msg`: mensagem de erro legível

Códigos de erro comuns:
- 400 Bad Request — validação Bean retorna a primeira violação. Ex: `{ "error": { "code": "400", "msg": "cpfCnpj: CPF ou CNPJ inválido" } }`
- 401 Unauthorized — token ausente/expirado/inválido. Ex: `{ "error": { "code": "401", "msg": "Token inválido" } }`
- 403 Forbidden — sem permissão sobre o recurso/conta. Ex: `{ "error": { "code": "403", "msg": "Acesso negado" } }`
- 404 Not Found — recurso não encontrado. Ex: `{ "error": { "code": "404", "msg": "Recurso não encontrado" } }`
- 409 Conflict — conflito de estado. Ex: `{ "error": { "code": "409", "msg": "Não é possível inativar uma cobrança já inativa" } }`
- 422 Unprocessable Entity — violação de regra de negócio (operação inválida no estado atual da conta/cobrança). Ex: `{ "error": { "code": "422", "msg": "Operação inválida para esta cobrança" } }`
- 500 Server Error — erro interno inesperado. Ex: `{ "error": { "code": "500", "msg": "Erro ao processar a solicitação" } }`

## Parâmetros de path reutilizados
- `accountId` (string) — Id da conta localizada dentro do portal do cliente. Ex: `133BD098-F481-48D6-6F7F-A357E09DEB45`
- `transactionId` (string) — Id da transação retornada na criação do PIX. Ex: `5E27E256-56AE-B023-9335-72C7ACD87B93`

---

# ENDPOINTS

## 1. Criar intenção de pagamento (PIX Dinâmico)
`POST /api/v2/movimentacao/{accountId}/pixCashIn`
Tag: Pagamentos · operationId: criarPixDinamico

Cria uma intenção de pagamento PIX dinâmico (imediato). Informe
`urlCallBackIntegrador` para receber a notificação de pagamento por webhook.
ATENÇÃO: este endpoint NÃO aplica Bean Validation — valores inválidos tendem a
resultar em 500.

Path params: accountId (obrigatório)

Request body (application/json) — PixDinamicoRequest:
- valorTotal (number, obrigatório) — Valor em reais (> 0). Ex: 18
- numeroPedido (string, obrigatório) — Identificador externo da cobrança no seu sistema
- conteudo (string, obrigatório) — Descrição da cobrança
- urlCallBackIntegrador (string uri, opcional) — URL HTTPS que receberá a notificação de pagamento (webhook). Vazio = sem notificação.

Exemplo de request:
```json
{
  "valorTotal": 18,
  "numeroPedido": "ID3455",
  "conteudo": "ID123",
  "urlCallBackIntegrador": "https://seu-sistema.com.br/webhooks/pix"
}
```

Resposta 200 — Intenção de pagamento criada (QR Code):
```json
{
  "data": {
    "transactionId": "E37CFF03-76F2-102A-9F42-C58AA360804F",
    "financialStatement": { "status": "CREATED" },
    "transactionType": "InstantPayment",
    "totalAmount": 18,
    "instantPayment": {
      "textContent": "00020101021226990014br.gov.bcb.pix...6304C290",
      "qrcodeURL": "https://pix-h.bpp.com.br/23114447/qrs1/v2/...",
      "generateImage": { "imageContent": "iVBORw0KGgo... (base64 PNG)", "mimeType": "image/png" },
      "dynamicQrCodeType": "IMMEDIATE"
    }
  }
}
```

Respostas de erro: 401, 403, 404, 422, 500

---

## 2. Criar cobrança PIX (Pix Cobrança) com vencimento
`POST /api/v2/movimentacao/{accountId}/pixCobranca`
Tag: Pagamentos · operationId: criarPixCobranca

Cria uma cobrança com vencimento; `valorTotal` é o mesmo em todas as parcelas.
Aplica Bean Validation (retorna 400 com a primeira violação).

Path params: accountId (obrigatório)

Request body (application/json) — PixCobrancaRequest:
- dadosCobranca (DadosCobranca, obrigatório)
- pagador (Pagador, obrigatório)
- regrasCobranca (RegrasCobranca, obrigatório)
- urlCallBack (string uri, obrigatório) — URL HTTPS de callback (webhook)

Exemplo de request:
```json
{
  "dadosCobranca": {
    "valorTotal": 55,
    "dataVencimento": "2026-02-20",
    "codigoExterno": "00123456",
    "conteudo": "Cobrança 0000"
  },
  "pagador": {
    "cpfCnpj": "22.317.952/0001-76",
    "razaoSocial": "Inova Sistemas Digitais Ltda",
    "nomeFantasia": "InovaTech",
    "segmento": "Desenvolvimento de Software",
    "email": "contato@inovatech.com.br",
    "telefoneCelular": "+55 21 98877-4455",
    "nomePagador": "Inova Sistemas Digitais Ltda",
    "logradouro": "Avenida das Américas, 3500",
    "cidade": "Rio de Janeiro",
    "bairro": "Barra da Tijuca",
    "uf": "RJ",
    "cep": "22640020"
  },
  "regrasCobranca": {
    "juros": 1,
    "multa": 2,
    "frequenciaCobranca": "MENSAL",
    "tipoMulta": "PERCENTUAL",
    "quantidadeParcelas": 1
  },
  "urlCallBack": "https://meusite.com/api/pix/callback"
}
```

Resposta 200 — Cobrança criada (lista de recibos):
```json
[
  {
    "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" }
    }
  }
]
```

Respostas de erro: 400, 401, 403, 422, 500

---

## 3. Criar cobrança PIX (Integração) com valores por parcela
`POST /api/v2/movimentacao/{accountId}/pixCobrancaIntegracao`
Tag: Pagamentos · operationId: criarPixCobrancaIntegracao

Igual à pixCobranca, mas `dadosCobranca` é uma LISTA (parcelas com valores
diferentes) e `regrasCobranca` usa `tipoJuros` (sem `frequenciaCobranca` /
`quantidadeParcelas`).

Path params: accountId (obrigatório)

Request body (application/json) — PixCobrancaIntegracaoRequest:
- dadosCobranca (array de DadosCobranca, obrigatório) — Parcelas com valores possivelmente diferentes
- pagador (Pagador, obrigatório)
- regrasCobranca (RegrasCobrancaIntegracao, obrigatório)
- urlCallBack (string uri, obrigatório)

Exemplo de request:
```json
{
  "dadosCobranca": [
    { "valorTotal": 55, "dataVencimento": "2026-02-20", "codigoExterno": "0012656", "conteudo": "Cobrança 1" },
    { "valorTotal": 45, "dataVencimento": "2026-03-20", "codigoExterno": "0345456", "conteudo": "Cobrança 2" }
  ],
  "pagador": {
    "cpfCnpj": "22.317.952/0001-76",
    "nomeFantasia": "InovaTech",
    "nomePagador": "Inova Sistemas Digitais Ltda",
    "cidade": "Rio de Janeiro",
    "uf": "RJ",
    "cep": "22640020"
  },
  "regrasCobranca": {
    "juros": 1,
    "multa": 2,
    "tipoMulta": "PERCENTUAL",
    "tipoJuros": "PERCENTUAL_MES_DIAS_UTEIS"
  },
  "urlCallBack": "https://meusite.com/api/pix/callback"
}
```

Resposta 201 — Cobranças criadas (uma transação por parcela):
```json
{
  "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 }
      }
    ]
  }
}
```

Respostas de erro: 400, 401, 403, 422, 500

---

## 4. Consultar status da transação
`GET /api/accounts/{accountId}/consultarTransactions/{transactionId}`
Tag: Pagamentos · operationId: consultarTransacao

Consulta o status atual de uma transação. Fallback útil quando o webhook não chega.

`transactionStatus` possíveis:
- CREATED — aguardando pagamento
- APPROVED — paga/concluída (considere paga APENAS quando APPROVED)
- REJECTED
- OPEN
- CANCELED
- PARTIAL
- UNFINISHED

Path params: accountId (obrigatório), transactionId (obrigatório)

Resposta 200 — Status da transação:
```json
{
  "data": {
    "transactions": [
      {
        "transactionId": "5E27E256-56AE-B023-9335-72C7ACD87B93",
        "endToEndId": "E23114447202411191116dZxvD1ZCzj8",
        "transactionStatus": "APPROVED",
        "totalAmount": 100,
        "paidAmount": 100,
        "transactionDate": "2024-11-19T08:16:44.598-03:00"
      }
    ]
  }
}
```

Respostas de erro: 401, 403, 404

---

## 5. Devolução (Refund) de uma transação PIX aprovada
`POST /api/movimentacao/{accountId}/instant-payments/{transactionId}/returns`
Tag: Devolução · operationId: devolverPix · x-mcp-name: devolucao_pix

Devolução total ou parcial. `returnReasonCode` deve ser um código do Banco
Central — consulte via operationId `consultarMotivosDevolucao`.

Path params: accountId (obrigatório), transactionId (obrigatório)

Request body (application/json) — DevolucaoRequest:
- externalIdentifier (string, obrigatório) — Identificador externo (idempotência)
- amount (number, obrigatório) — Valor da devolução (total ou parcial)
- returnReasonCode (string, obrigatório) — Código BACEN (ver consultarMotivosDevolucao). Comum: MD06

Exemplo de request:
```json
{
  "externalIdentifier": "d81540e9-e579-4352-9b98-00552cb39164",
  "amount": 50,
  "returnReasonCode": "MD06"
}
```

Resposta 200 — Devolução registrada:
```json
{ "data": { "transactionId": "6FA62ACC-E448-D51D-C3AA-9D4EA2BDCEA0" } }
```

Respostas de erro: 400, 401, 404, 422, 500

---

## 6. Consultar códigos de motivo de devolução (BACEN)
`GET /api/movimentacao/instant-payments/{country}/return-codes`
Tag: Devolução · operationId: consultarMotivosDevolucao

Path params:
- country (string, obrigatório) — País (ISO). Brasil = BR. Ex: BR

Resposta 200 — Lista de códigos válidos (fornecida pelo PSP/BACEN)

Respostas de erro: 401

---

## 7. Reemissão de cobranças em PDF
`POST /api/v2/cobranca-cliente-final/{accountId}/reemissao-pix-cobranca`
Tag: Cobranças · operationId: reemitirPdf · x-mcp-name: reemissao_pdf

Retorna os bytes do PDF. A resposta é BINÁRIA (application/pdf).

Path params: accountId (obrigatório)

Request body (application/json) — ReemissaoRequest:
- movimentacaoIds (array de integer, obrigatório) — Nº dos documentos (numeroDocumento) das cobranças

Exemplo de request:
```json
{ "movimentacaoIds": [1949] }
```

Resposta 200 — Bytes do PDF (application/pdf, binário)

Respostas de erro: 401, 404

---

## 8. Inativar cobrança com vencimento
`DELETE /api/v2/cobranca-cliente-final/{id}/inativar`
Tag: Cobranças · operationId: inativarCobranca

Inativa uma cobrança com vencimento (role CLIENTE). Se for da integração Fiserv,
também cancela no PSP.

Path params:
- id (integer, obrigatório) — ID da cobrança (numeroDocumento). Ex: 7896

Resposta 200 — Inativada:
```json
{ "status": "Cobrança inativada com sucesso" }
```

Respostas de erro: 403, 404, 409, 422

---

# WEBHOOK — Notificação de pagamento (LC Pay → seu sistema)

Evento: `pixPayment` · operationId: webhookPixPayment
Método: POST na URL de callback que você informou.

Enviado quando um PIX gerado pela API é pago. O CORPO É VAZIO; todos os dados vão
nos HEADERS. Ativado por transação via `urlCallBackIntegrador` (PIX dinâmico) ou
`urlCallBack` (cobrança).

Em falha, o LC Pay reenvia (~2 min, até ~30 tentativas). Responda 2xx e trate de
forma IDEMPOTENTE por `webhook-transaction-id`.

Headers recebidos:
- webhook-event-type — Tipo do evento. Atualmente sempre `pix.payment`.
- webhook-transaction-id — transactionId da transação — chave de conciliação.
- webhook-external-code — codigoExterno da cobrança; vazio no PIX dinâmico.
- X-Api-Key — Chave de autenticação da notificação. VALIDE antes de processar.

Resposta esperada: 200 — Notificação aceita. Qualquer não-2xx/timeout entra na
fila de retry.

---

# SCHEMAS (referência de campos)

## PixDinamicoRequest
- valorTotal (number, obrigatório) — Valor em reais (> 0). Ex: 18
- numeroPedido (string, obrigatório) — Identificador externo da cobrança no seu sistema
- conteudo (string, obrigatório) — Descrição da cobrança
- urlCallBackIntegrador (string uri, opcional) — URL HTTPS de webhook. Vazio = sem notificação.

## DadosCobranca
- valorTotal (number, obrigatório) — Valor da parcela (>= 0.01). Ex: 55
- dataVencimento (string date, obrigatório) — Hoje ou futuro (não pode ser anterior à data atual). Ex: "2026-02-20"
- codigoExterno (string, opcional, maxLength 100)
- conteudo (string, opcional, maxLength 90)

## Pagador
- cpfCnpj (string, obrigatório) — CPF (11) ou CNPJ (14) válido. Ex: "22.317.952/0001-76"
- nomeFantasia (string, obrigatório)
- nomePagador (string, obrigatório, maxLength 100)
- cidade (string, obrigatório, maxLength 80)
- razaoSocial (string, opcional)
- segmento (string, opcional)
- email (string email, opcional)
- telefoneCelular (string, opcional)
- logradouro (string, opcional, maxLength 150)
- bairro (string, opcional)
- uf (string, opcional) — Padrão `^[A-Z]{2}$`; se enviado, 2 letras maiúsculas
- cep (string, opcional) — Padrão `^\d{8}$`; se enviado, 8 dígitos

## RegrasCobranca (usado em pixCobranca)
- juros (number, obrigatório, minimum 0)
- multa (number, obrigatório, minimum 0)
- quantidadeParcelas (integer, obrigatório, 1 a 12)
- frequenciaCobranca (string, opcional) — enum: MENSAL, SEMANAL
- tipoMulta (string, opcional) — enum: PERCENTUAL, FIXO

## RegrasCobrancaIntegracao (usado em pixCobrancaIntegracao)
- juros (number, obrigatório, minimum 0)
- multa (number, obrigatório, minimum 0)
- tipoMulta (string, opcional) — enum: PERCENTUAL, FIXO
- tipoJuros (string, opcional) — enum: PERCENTUAL_DIA_DIAS_CORRIDOS, PERCENTUAL_MES_DIAS_UTEIS (apenas estes dois valores estão ativos)

## PixCobrancaRequest
- dadosCobranca (DadosCobranca, obrigatório)
- pagador (Pagador, obrigatório)
- regrasCobranca (RegrasCobranca, obrigatório)
- urlCallBack (string uri, obrigatório)

## PixCobrancaIntegracaoRequest
- dadosCobranca (array de DadosCobranca, obrigatório)
- pagador (Pagador, obrigatório)
- regrasCobranca (RegrasCobrancaIntegracao, obrigatório)
- urlCallBack (string uri, obrigatório)

## DevolucaoRequest
- externalIdentifier (string, obrigatório) — idempotência
- amount (number, obrigatório) — valor total ou parcial
- returnReasonCode (string, obrigatório) — código BACEN. Comum: MD06

## ReemissaoRequest
- movimentacaoIds (array de integer, obrigatório) — numeroDocumento das cobranças

## ErrorResponse
- error.code (string) — código HTTP como string. Ex: "409"
- error.msg (string) — mensagem de erro legível

---

# RECEITAS DE INTEGRAÇÃO PONTA A PONTA

## Receita 1: conciliar_pix_dinamico
PIX dinâmico com conciliação automática por webhook.
1. Crie o PIX com criarPixDinamico, informando `urlCallBackIntegrador` (sua URL HTTPS de callback).
2. Guarde o `data.transactionId` retornado — é a chave de conciliação.
3. Apresente ao pagador o copia-e-cola (`instantPayment.textContent`) e/ou o QR (`generateImage.imageContent`, base64 PNG).
4. Ao ser pago, o LC Pay faz POST na sua URL com os dados nos headers (veja WEBHOOK).
5. No recebimento: valide `X-Api-Key`, concilie por `webhook-transaction-id`, responda 2xx e processe de forma idempotente.
6. Fallback opcional: se não receber o webhook, use consultarTransacao para checar o `transactionStatus`.

NOTA: Sem `urlCallBackIntegrador` nenhum webhook é disparado — a conciliação
depende de polling via consultarTransacao.

## Receita 2: cobranca_com_vencimento
Cobrança PIX com vencimento e reemissão de PDF.
1. Crie a cobrança com criarPixCobranca (parcelas de mesmo valor) ou criarPixCobrancaIntegracao (valores diferentes por parcela).
2. Guarde, por parcela, o `numeroDocumento` (para reemissão/inativação) e o `transactionId`/`transacaoId` (para consulta/conciliação).
3. Entregue ao pagador o link do PDF (`documento.link`) e/ou o copia-e-cola.
4. Receba a confirmação de pagamento pelo webhook (`webhook-external-code` traz o codigoExterno da cobrança).
5. Para reenviar o documento, use reemitirPdf com os `movimentacaoIds` (= numeroDocumento).
6. Para cancelar uma cobrança em aberto, use inativarCobranca com o `id` (= numeroDocumento).