Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

Nesta jornada, o usuário pagador inicia a experiência ao escanear um QR Code que contém duas informações integradas: uma cobrança Pix imediata, a ser paga no momento da leitura, e os dados da recorrência do Pix Automático, que definem as condições de pagamento para cobranças futuras.

O ponto central desta jornada é que o pagamento da cobrança imediata implica automaticamente a aceitação do Pix Automático como forma de pagamento para as cobranças subsequentes.

Na Jornada 3, de forma resumida, o aceite ao Pix Automático é obrigatório caso o cliente pague o Qr Code (diferente da Jornada 4, que é opcional).

🚧
Importante
Caso o usuário não concorde com as condições da recorrência, o pagamento não poderá ser realizado.

Passos para Integrar

Cliente realiza a leitura de um QR Code (Passo no seu sistema).
Realizar autenticação na API (para decodificação do QR Code) - [API Reference]
Realizar a decodificação/consulta dos dados do QR Code via API - [API Reference]
Exibir os dados da solicitação de recorrência e as informações de pagamento (obtidos via API) ao cliente (Passo no seu sistema).
Cliente decide prosseguir com o pagamento. (Ao confirmar o pagamento, o cliente também aceitará automaticamente a recorrência vinculada) (Passo no seu sistema).
Realizar o pagamento do QR Code via API - [API Reference]
Receber Webhook com o status do pagamento (Evento: XX)
Se o pagamento for liquidado: Receber Webhook com a confirmação e os detalhes da recorrência estabelecida (Evento:

Caso seja necessário, você pode consultar o status da recorrência manualmente:

Consultar status do pagamento do QR Code - [API Reference]
Consultar status da recorrência por ID - [API Reference]

Fluxo de Integração

Consulta de QR Code EMV

Exemplo /emv

{
    "emv": "00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80950014br.gov.bcb.pix2573qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/420e49420b1b469ab628c3a51430d4d56304E09F"
}

Resposta

{
    "type": "5",
    "collection": "1",
    "payloadFormatIndicator": "02",
    "merchantAccountInformation": {
        "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/0513bd598a59239884b9fbb9b5e788",
        "gui": "br.gov.bcb.pix",
        "key": "[email protected]",
        "additionalInformation": null,
        "withdrawalServiceProvider": "00000000"
    },
    "merchantCategoryCode": 0,
    "transactionCurrency": 0,
    "transactionAmount": 20.00,
    "countryCode": null,
    "merchantName": "Fulano de Ta teste",
    "merchantCity": "Barueri",
    "postalCode": null,
    "initiationMethod": null,
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000242504",
    "recorrency":{
         "id":"RR0435879820240605njua7shf40o",
         "journeyType":2,
         "interval":{
            "start":"2024-01-10",
            "end":"2026-01-10",
            "frequencyType":"MONTHLY"
         },
         "amount":0,
         "maxValueFloor":550,
         "creditParty":{
            "ispb":4358798,
            "taxId":"61695227000193",
            "name":"Enel"
         },
         "debtor":{
            "taxId":"4623217035",
            "name":"Ciclano da Silva",
            "personType":"NATURAL_PERSON"
         },
         "contract":{
            "number":"1234567890ABC",
            "description":"Conta de energia"
         }
      }
}

Na resposta o Qr Code terá o type 5

Exemplo /emv/full

{
    "emv": "00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80950014br.gov.bcb.pix2573qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/420e49420b1b469ab628c3a51430d4d56304E09F"
}

Resposta

{
   "version":"1.0.0",
   "status":200,
   "body":{
      "type":"COMPOSED",
      "merchantAccountInformation":{
         "url":"ex.com.br/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8",
         "gui":"br.gov.bcb.pix",
         "merchantCategoryCode":"0000",
         "additionaldata":"Obrigado por comprar",
         "withdrawalServiceProvider":"13935893",
         "merchantName":"Empresa S.A.",
         "merchantCity":"Barueri",
         "postalCode":"20770000"
      },
      "key":null,
      "amount":null,
      "transactionIdentification":null,
      "payload":null,
      "recorrency":{
         "id":"RR0435879820240605njua7shf40o",
         "journeyType":2,
         "interval":{
            "start":"2024-01-10",
            "end":"2026-01-10",
            "frequencyType":"MONTHLY"
         },
         "amount":0,
         "maxValueFloor":550,
         "creditParty":{
            "ispb":4358798,
            "taxId":"61695227000193",
            "name":"Enel"
         },
         "debtor":{
            "taxId":"4623217035",
            "name":"Ciclano da Silva",
            "personType":"NATURAL_PERSON"
         },
         "contract":{
            "number":"1234567890ABC",
            "description":"Conta de energia"
         }
      }
   }
}

Na resposta o Qr Code terá o type COMPOSED

Após identificar o Qr Code como Qr Code de Jornada 3 deve-se exibir essas informações ao usuário pagador.

Exibição da Solicitação e Coleta da Decisão do Cliente Final 🙋‍♂️❓

É necessário coletar todos os dados que serão exibidos para o cliente final, para que o mesmo possa decidir se aceitará ou recusará a proposta de consentimento ao Pix Automático.

Essa exibição deve incluir:

Nome do recebedor (Nome Fantasia ou Razão Social).
Valor e periodicidade da cobrança .
Data de início da cobrança.
Validade da autorização (data-limite para aceitação).
Identificador único da solicitação de recorrência (ID).

O usuário pagador deve, então, decidir se deseja autorizar ou recusa a cobrança futura automática via Pix.

Para isso, o sistema integrador deve:

Garantir que a decisão do usuário seja tomada de forma ativa e autenticada (ex: PIN, biometria, senha etc).
Enviar essa decisão para a Celcoin utilizando um dos endpoints dedicados:

Envio da Resposta da Autorização via API 🚀

Aceite:

PATCH: /recurrencies/authorization/{id}/accept
Parâmetro: id

{  
  "maxAmount": 100  //Valor máximo aceitável para a recorrência especificada.
}

Exemplo de resposta de Sucesso

{  
  "status": 200,  
  "version": "1.0",  
  "body": {  
    "id": "RR0435879820240920njua7shf40o",  
    "deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN",  
    "cancellingReason": "ACCOUNT_CANCELLATION",  
    "status": "PENDING_CREDIT_PARTY",  
    "journeys": [  
      {  
        "status": "ACCEPTED",  
        "type": 1,  
        "accepetedDate": "2025-05-10T10:15:00Z",  
        "denyDate":null  
      }  
    ],  
    "interval": {  
      "start": "2025-06-01T00:00:00Z",  
      "end": "2025-12-01T00:00:00Z",  
      "frequencyType": "MONTHLY"  
    },  
    "frequencyType": "MONTHLY",  
    "amount": 50,  
    "creditParty": {  
      "taxId": "12345678000199",  
      "name": "Loja Virtual Ltda"  
      "bank":"13935893"  
    },  
    "debitParty": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "bank": "13935893",  
      "branch":"4444",  
      "branch":"0001",  
      "account": "12345-6",  
      "stateCode": "SP"  
    },  
    "debtor": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "name": "João da Silva"  
    },  
    "contract": {  
      "number": "CONTR-2025-PIX-001",  
      "description": "Assinatura mensal do plano premium"  
    },  
    "cancellation": null,  
    "createDate": "2025-05-01T08:00:00Z",  
    "updateDate": "2025-05-15T10:30:00Z",  
    "deleteDate": "2025-05-20T00:00:00Z",  
    "cancelledDate": "2025-05-16T15:03:07.709Z"  
  }  
}

Recusa:

PATCH /recurrencies/authorization/{id}/deny

Parâmetro: id

{
  "deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN"
}

Tipo de rejeição:

Valor	Descrição
CREDIT_PARTY_IS_NOT_KNOWN	O usuário pagador não reconhece o usuário recebedor ou não tem qualquer tipo de relacionamento ativo com ele.
NOT_INTERESTED	O usuário pagador não tem interesse no uso do Pix Automático para pagar as cobranças referentes àquele usuário recebedor.
NOT_OFFERED_TO_LEGAL_PERSON	Não oferecido para pessoa jurídica.

Exemplo de resposta de Sucesso (revisar contrato)

{  
  "status": 200,  
  "version": "1.0",  
  "body": {  
    "id": "RR0435879820240920njua7shf40o",  
    "deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN",  
    "cancellingReason": "ACCOUNT_CANCELLATION",  
    "status": "PENDING_CREDIT_PARTY",  
    "journeys": [  
      {  
        "status": "ACCEPTED",  
        "type": 1,  
        "accepetedDate": "2025-05-10T10:15:00Z",  
        "denyDate":null  
      }  
    ],  
    "interval": {  
      "start": "2025-06-01T00:00:00Z",  
      "end": "2025-12-01T00:00:00Z",  
      "frequencyType": "MONTHLY"  
    },  
    "frequencyType": "MONTHLY",  
    "amount": 50,  
    "creditParty": {  
      "taxId": "12345678000199",  
      "name": "Loja Virtual Ltda"  
      "bank":"13935893"  
    },  
    "debitParty": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "bank": "13935893",  
      "branch":"4444",  
      "branch":"0001",  
      "account": "12345-6",  
      "stateCode": "SP"  
    },  
    "debtor": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "name": "João da Silva"  
    },  
    "contract": {  
      "number": "CONTR-2025-PIX-001",  
      "description": "Assinatura mensal do plano premium"  
    },  
    "cancellation": null,  
    "createDate": "2025-05-01T08:00:00Z",  
    "updateDate": "2025-05-15T10:30:00Z",  
    "deleteDate": "2025-05-20T00:00:00Z",  
    "cancelledDate": "2025-05-16T15:03:07.709Z"  
  }  
}

Estrutura do JSON

Campo	Tipo	Descrição
status	int	Código de status da resposta.
version	string	Versão do payload.
body	object	Dados principais do recurso.

Estrutura do objeto Body

Campo	Tipo	Descrição
id*	string	Identificador único da recorrencia
deniedReason	ENUM (CREDIT_PARTY_IS_NOT_KNOWN, NOT_INTERESTED, NOT_OFFERED_TO_LEGAL_PERSON)	Motivo da recusa, se aplicável.
cancellingReason	ENUM (ACCOUNT_CANCELLATION, CREDIT_PARTY_END_OF_ACTIVITIES, PAYER_DEAD, CONFIRMATION_ERROR, FRAUD, CONFIRMED_IN_OTHER_JOURNEY, CREDIT_PARTY_REQUEST, DEBIT_PARTY_REQUEST, TIMEOUT)	Motivo do cancelamento, se aplicável
status*	ENUM (PENDING_DEBIT_PARTY, PENDING_CREDIT_PARTY, CONFIRMED, CANCELLATION_REQUEST, CANCELLING, CANCELLED, EXPIRED, ERROR)	status da recorrencia
journeys*	array de objetos	Lista de jornadas requisitadas para a recorrencia
interval*	objeto	Informações de intervalo da recorrência
frequencyType*	Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)	Frequência da recorrência
amount	decimal	Valor do pagamento recorrente
creditParty*	objeto	Dados do Recebedor
debitParty*	objeto	Dados do pagador
debtor	objeto	Pessoa ou empresa devedora.
contract*		Dados do contrato associado à cobrança
cancellation	objeto	Dados do cancelamento, se houver
createDate*	string (ISO 8601)	Data de criação da recorrencia
updateDate	string (ISO 8601)	Data da última atualização
deleteDate	string (ISO 8601)	Data de exclusão, se houver
cancelledDate	string (ISO 8601)	Data em que foi cancelada.

Envio da confirmação da Autorização via API 🚀

A instituição recebedora, após validar a decisão do cliente final, nos envia um webhook com a confirmação e todos os dados da solicitação. Essas informações, constituindo o comprovante da operação, são então encaminhadas por nós a você.

Exemplo de Contrato do Webhook de Confirmação Final:

{  
  "status": 200,  
  "version": "1.0",  
  "body": {  
    "id": "RR0435879820240920njua7shf40o",  
    "deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN",  
    "cancellingReason": "ACCOUNT_CANCELLATION",  
    "status": "PENDING_CREDIT_PARTY",  
    "journeys": [  
      {  
        "status": "ACCEPTED",  
        "type": 1,  
        "accepetedDate": "2025-05-10T10:15:00Z",  
        "denyDate":null  
      }  
    ],  
    "interval": {  
      "start": "2025-06-01T00:00:00Z",  
      "end": "2025-12-01T00:00:00Z",  
      "frequencyType": "MONTHLY"  
    },  
    "frequencyType": "MONTHLY",  
    "amount": 50,  
    "creditParty": {  
      "taxId": "12345678000199",  
      "name": "Loja Virtual Ltda"  
      "bank":"13935893"  
    },  
    "debitParty": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "bank": "13935893",  
      "branch":"4444",  
      "branch":"0001",  
      "account": "12345-6",  
      "stateCode": "SP"  
    },  
    "debtor": {  
      "personType": "NATURAL_PERSON",  
      "taxId": "98765432100",  
      "name": "João da Silva"  
    },  
    "contract": {  
      "number": "CONTR-2025-PIX-001",  
      "description": "Assinatura mensal do plano premium"  
    },  
    "cancellation": null,  
    "createDate": "2025-05-01T08:00:00Z",  
    "updateDate": "2025-05-15T10:30:00Z",  
    "deleteDate": "2025-05-20T00:00:00Z",  
    "cancelledDate": "2025-05-16T15:03:07.709Z"  
  }  
}

❗️
Esta documentação ainda está sujeita a atualizações. Quando tivermos a versão final publicada, este aviso será removido de todas as páginas.

Autorização - Jornada 3

Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

🚧
Importante

Passos para Integrar

Fluxo de Integração

Consulta de QR Code EMV

Exibição da Solicitação e Coleta da Decisão do Cliente Final 🙋‍♂️❓

Essa exibição deve incluir:

Envio da Resposta da Autorização via API 🚀

Aceite:

Recusa:

Envio da confirmação da Autorização via API 🚀

❗️
Esta documentação ainda está sujeita a atualizações. Quando tivermos a versão final publicada, este aviso será removido de todas as páginas.

Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

🚧Importante

Passos para Integrar

Fluxo de Integração

Consulta de QR Code EMV

Exibição da Solicitação e Coleta da Decisão do Cliente Final 🙋‍♂️❓

Essa exibição deve incluir:

Envio da Resposta da Autorização via API 🚀

Aceite:

Recusa:

Envio da confirmação da Autorização via API 🚀

❗️Esta documentação ainda está sujeita a atualizações. Quando tivermos a versão final publicada, este aviso será removido de todas as páginas.

🚧
Importante

❗️
Esta documentação ainda está sujeita a atualizações. Quando tivermos a versão final publicada, este aviso será removido de todas as páginas.