Pagamentos

Por QR Code

Iniciar pagamento Pix a partir do payload EMV (estático, dinâmico ou composto)

Decodifica o BR Code (QR copia e cola), extrai recebedor/valor/tipo e persiste o pagamento com status INICIADO (status: "0").

Endpoint

POST /api/v2/pix/pagamentos/qrcode

Scope: pix.write

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer {{access_token}}`
`Accept`	Sim	`application/json`
`Content-Type`	Sim	`application/json`

Body

{
  "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
  "municipio": "São Paulo",
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "codMunIbge": "3550308",
  "data_agendada": "2026-07-10T10:00:00Z",
  "valorMaximo": 150.00
}

Campo	Obrigatório	Descrição
`qrcode`	Sim	Payload EMV (string copia e cola)
`municipio`	Sim*	Município do pagador (decodificação JDPI)
`txid`	Não	Usado se o QR não trouxer conciliação; senão gerado
`codMunIbge`	Não	Código IBGE — relevante em QR composto (Pix Automático)
`data_agendada`	Não	Data agendada (ISO 8601)
`valorMaximo`	Não	Teto do pagador em QR composto

*Conforme contrato da API; em homologação o mínimo operacional costuma incluir qrcode (e municipio quando exigido pela decodificação).

Retorno — variações por tipo de QR

Tipo de QR	`tipo`	`valor`	`chave`	`rec_status`
Estático (`qres`)	`2`	Fixo do QR ou `0`	Sim, se o QR tiver chave	`null`
Dinâmico (`qrdn`)	`3`	`valorOriginal` / `valorFinal` (COBV)	Sim, se presente	`null`
Composto / Pix Automático (`paut`)	`8`	Valor da cobrança imediata do composto	Conforme QR	Status da `solicrec` (ex.: `"CRIADA"`)

Sempre presentes na iniciação por QR:

endToEndId — da decodificação
status — "0"
tipo_transacao — -1
recebedor / pagador

Schema completo: Visão geral.

Exemplo — QR dinâmico

{
  "id": "c4f1a2b3-8d9e-4f10-a1b2-c3d4e5f67890",
  "endToEndId": "E382973742026070812600ABC1234567890",
  "chave": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "valor": 49.90,
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "status": "0",
  "tipo": 3,
  "id_req": null,
  "recebedor": {
    "pessoa": {
      "nome": "Loja Exemplo LTDA",
      "cpfCnpj": "12345678000199",
      "tipo": 1
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00001234",
      "tipo": 0
    }
  },
  "pagador": {
    "pessoa": {
      "nome": "João Silva Exemplo",
      "cpfCnpj": "39053344705",
      "tipo": 0
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00005678",
      "tipo": 0
    }
  },
  "dataHoraCriacao": "2026-07-08T13:00:00.000000Z",
  "dataHoraAtualizacao": "2026-07-08T13:00:00.000000Z",
  "tipo_transacao": -1,
  "rec_status": null
}

Exemplo — QR estático (valor aberto)

Quando o QR estático não define valor, valor retorna 0:

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "endToEndId": "E382973742026070813000DEF9876543210",
  "chave": "[email protected]",
  "valor": 0,
  "txid": "abc123def456ghi789jkl012mno345",
  "status": "0",
  "tipo": 2,
  "id_req": null,
  "tipo_transacao": -1,
  "rec_status": null
}

Exemplo — QR composto (Pix Automático)

{
  "id": "d5e6f7a8-b9c0-1234-def0-123456789abc",
  "endToEndId": "E382973742026070814000GHI1122334455",
  "chave": "chave-evp-do-recebedor",
  "valor": 25.00,
  "txid": "txidDaCobrancaImediataNoComposto",
  "status": "0",
  "tipo": 8,
  "id_req": null,
  "tipo_transacao": -1,
  "rec_status": "CRIADA"
}

Exemplo cURL

curl --location 'https://api-h.nuvende.com.br/api/v2/pix/pagamentos/qrcode' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "qrcode": "{{pix_copia_e_cola}}",
  "municipio": "São Paulo"
}'

Próximo passo

Confirmar pagamento com o id (e o valor, se ainda for 0 ou se precisar ajustar conforme regras do QR).

Por chave

Iniciar pagamento Pix consultando a chave no DICT

Confirmar

Efetivar um pagamento Pix previamente iniciado