Criação de CCB — Pagamento via QR Code PIX (EMV)

Visão Geral

Neste fluxo, o desembolso da CCB é realizado via QR Code PIX (EMV). Em vez de informar dados de boleto, o payload carrega o código EMV previamente validado e a chave PIX do beneficiário.

O fluxo exige uma etapa de validação do QR Code antes da criação da Application — o campo qrcode_emv enviado deve ser o retorno do endpoint /validate-pix-emv, garantindo que valor e destinatário coincidam com os termos da proposta.

1. Validar o QR Code EMV → POST /validate-pix-emv
   ↓
2. Criar a Application com payment_method: QRCODE_PIX
   ↓
3. Fluxo normal de assinatura e desembolso

Etapa 1 — Validação do QR Code EMV

Antes de criar a Application, o QR Code deve ser validado para confirmar que o valor e o destinatário são compatíveis com a operação.

POST /banking/originator/validate-pix-emv

{
  "qrcode_emv": "00020101021126580014br.gov.bcb.pix0136655c6978-294b-449e-b996-7c156f73587b52040000530398654041.005802BR5913Celcoin Teste6009Sao Paulo62070503***6304E32D"
}

O retorno desta chamada fornece a pix.key e confirma que o EMV é válido para uso na criação da Application. Sempre use o qrcode_emv retornado por este endpoint — nunca envie um EMV bruto sem validação prévia.

Etapa 2 — Criação da Application

Endpoint

POST /banking/originator/applications

Payload Completo

{
  "product": {
    "id": "d4e5252f-f3fc-47a3-8ef9-7a8d9ff4e60f"
  },
  "borrower": {
    "id": "a03f9d67-1afa-48df-b1c5-537be306f26e"
  },
  "funding": {
    "id": "7b8432fb-34e7-4f14-ba6a-a24dc2b29c35"
  },
  "simulation_id": "e5d70282-00be-4ce9-8ec3-a66b88a42f56",
  "payment_method": "QRCODE_PIX",
  "beneficiary_account": {
    "pix": {
      "key": "655c6978-294b-449e-b996-7c156f73587b",
      "key_type": "ALEATORY_KEY"
    },
    "qrcode_emv": "00020101021126580014br.gov.bcb.pix0136655c6978-294b-449e-b996-7c156f73587b52040000530398654041.005802BR5913Celcoin Teste6009Sao Paulo62070503***6304E32D"
  }
}

Referência de Campos

Campos raiz

Campo	Tipo	Obrigatório	Descrição
`product.id`	uuid	sim	ID do produto configurado
`borrower.id`	uuid	sim	ID do tomador cadastrado
`funding.id`	uuid	sim	ID do fundo/originador
`simulation_id`	uuid	sim	Retornado pelo endpoint `/preview`. Vincula os dados da simulação
`payment_method`	enum	sim	Método de pagamento do desembolso. `QRCODE_PIX` para este fluxo
`beneficiary_account`	object	sim	Dados do beneficiário do desembolso via PIX

Objeto `beneficiary_account`

Campo	Tipo	Obrigatório	Descrição
`pix.key`	string	sim	Chave PIX do beneficiário — retornada pela validação do EMV
`pix.key_type`	enum	sim	Tipo da chave PIX. Ver tabela de tipos abaixo
`qrcode_emv`	string	sim	Código EMV ("Copia e Cola") previamente validado via `/validate-pix-emv`

Tipos de Chave PIX Suportados

`key_type`	Formato esperado em `key`
`EMAIL`	`[email protected]`
`TAXPAYER_ID`	CPF: `12345678900` · CNPJ: `12345678000100` (somente números)
`PHONE_NUMBER`	`+5511999999999` (com DDI)
`ALEATORY_KEY`	UUID aleatório gerado pelo banco (chave aleatória)

Diferenças em Relação ao Fluxo de Boleto

	Pagamento via Boleto	Pagamento via QR Code PIX
`payment_method`	`BILLET_PAYMENT`	`QRCODE_PIX`
Dados de pagamento	`billets_info`	`beneficiary_account`
Validação prévia	Não exige	Obrigatório via `/validate-pix-emv`
Chave de destino	Código de barras	Chave PIX + EMV

Observações Importantes

qrcode_emv deve ser validado previamente — enviar um código EMV bruto sem passar pelo /validate-pix-emv resultará em erro de processamento. A validação garante que o valor do QR Code é compatível com o valor da simulação e que o destinatário é o beneficiário esperado.

simulation_id — expira após um período configurado no produto. Sempre crie a Application logo após a simulação para evitar expiração.

billets_info não deve ser enviado neste fluxo — é exclusivo para liquidação de boletos via código de barras e será ignorado ou retornará erro se enviado junto com payment_method: QRCODE_PIX.

Erros Comuns

Situação	Causa provável
QR Code recusado no desembolso	`qrcode_emv` não foi validado via `/validate-pix-emv` antes do envio
Valor divergente	Valor embutido no EMV não corresponde ao valor da simulação
Chave PIX inválida	`pix.key` não corresponde ao destinatário codificado no `qrcode_emv`
`simulation_id` expirado	Tempo entre simulação e criação excedeu o limite configurado no produto

Documento gerado para integração técnica. Em caso de dúvidas, acione o time de suporte via canal dedicado.