Jornadas 4

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

Nesta jornada, o usuário pagador realiza ou agenda um pagamento via QR Code, e, após a conclusão dessa operação, é ofertada a possibilidade de autorizar o Pix Automático como forma de pagamento para futuras cobranças. A autorização da recorrência será solicitada somente após o pagamento .A aceitação da recorrência é obrigatória para dar continuidade ao processo de autorização.

Passos para Integrar

Fase 1: Pagamento ou Agendamento Inicial via QR Code

Cliente inicia um pagamento e 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 detalhes do pagamento ao cliente para confirmação (Passo no seu sistema).
Cliente confirma a intenção de realizar o pagamento (Passo no seu sistema).
Realizar o pagamento do QR Code via API - [API Reference]
Receber Webhook com o status do pagamento (Evento: XX)

Fase 2: Oferta e Autorização do Pix Automático para Futuras Cobranças

Após a confirmação de conclusão bem-sucedida do pagamento/agendamento inicial (conforme Webhook do Passo 7): Ofertar ao cliente a opção de autorizar o Pix Automático para futuras cobranças do mesmo recebedor/serviço (Passo no seu sistema).
Cliente analisa a oferta e decide se aceita ou recusa a autorização do Pix Automático (Passo no seu sistema).
Comunicar a decisão do cliente à Celcoin:
1. Se autorizado pelo cliente: Enviar a autorização da recorrência - [API Reference]
  ou
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) - [API Reference]

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

O usuário inicia a jornada escaneando o QR Code . Seu sistema deve enviar esse dado para o endpoint de decodificação do QR Code:

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 qrcode 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 qrcode terá o type COMPOSED

Após identificar o qrcode como qrcode de Jornada 2 deve exibir essas informações ao usuário pagador.

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

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"  
  }  
}