Jornada 2 : Autorização de Recorrência via QR Code (sem cobrança vinculada)

Nesta jornada, o usuário pagador lê um QR Code contendo exclusivamente os dados de uma recorrência (sem cobrança associada, diferente do que ocorrerá nas jornadas 3 e 4).

A experiência do pagador envolve visualizar os dados, autorizar a recorrência e, se autorizado, comunicar o aceite ao PSP recebedor.

O usuário inicia a jornada lendo um QR Code com os dados da recorrência, que será via consulta de emv: Realizar um Pix Cash-Out por QR Code Dinâmico

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 (obtidos via API) ao cliente (Passo no seu sistema).
Cliente decide se aceita ou recusa a solicitação de recorrência (Passo no seu sistema).
Comunicar a decisão do cliente à Celcoin:
1. 6.1. Se autorizado pelo cliente: Enviar a autorização da recorrência - API Reference]
  ou
2. 6.2. Se recusado pelo cliente: Enviar a recusa da recorrência - [API Reference]
Receber Webhook com o resultado do processamento da recorrência (Evento: XX)

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

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": "3",
    "collection": null,
    "payloadFormatIndicator": null,
    "merchantAccountInformation": {
        "url": "bx.com.br/JDPI/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8=",
        "gui": "br.gov.bcb.pix",
        "key": null,
        "additionalInformation": null,
        "withdrawalServiceProvider": null
    },
    "merchantCategoryCode": 0,
    "transactionCurrency": 0,
    "transactionAmount": 0,
    "countryCode": null,
    "merchantName": null,
    "merchantCity": null,
    "postalCode": null,
    "initiationMethod": null,
    "transactionIdentification": 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 3 e o objeto de recorrência.

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 2 de adesão ao Pix Automático, 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 🚀

Após o aceite do cliente, a Celcoin notificará o PSP recebedor, que 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 consentimento e adesão ao Pix Automático, são então encaminhadas pela Celcoin para os clientes.

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 2

Jornada 2 : Autorização de Recorrência via QR Code (sem cobrança vinculada)

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 2 : Autorização de Recorrência via QR Code (sem cobrança vinculada)

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.

❗️
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.