Autorização - Jornada 2

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, referente aos dados da recorrência. Na seção abaixo mostraremos os campos que devem ser exibidos.

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:

POST: /recurrencies/authorization/accept

{
  "id": "RR0435879820240920njua7shf40o",
  "endToEnd": null,
  "journeyType":2
  "interval": {
    "start": "2025-06-01T00:00:00Z",
    "end": "2025-12-01T00:00:00Z",
    "frequencyType": "MONTHLY"
  },
  "amount": 0,
  "maxAmount": 0,
  "creditParty": {
    "taxId": "12345678000199",
    "name": "Academia Corpo e Movimento",
    "bank": "0000000"
  },
  "debitParty": {
    "personType": "FISICA",
    "taxId": "98765432100",
    "bank": "12345678",
    "account": "98765-4",
    "branch": "0001",
    "stateCode": "1234456"
  },
  "debtor": {
    "personType": "NATURAL_PERSON",
    "taxId": "98765432100",
    "name": "João da Silva"
  },
  "contract": {
    "number": "CTR-2025-PIX-01",
    "description": "Assinatura mensal do plano premium"
  }
}

Exemplo de resposta de Sucesso

{
  "status": 200,
  "version": "1.0",
  "body": {
    "id": "RR0435879820240920njua7shf40o",
    "deniedReason":null,
    "cancellingReason":null,
    "status": "ACCEPTED",
    "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"
      "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": null,
    "cancelledDate": null
  }
}

Exemplo de resposta com erro

{
  "status": 400,
  "version": "v1.0.0",
  "error": {
    "errorCode": "CBE215",
    "message": "Não foi encontrada nenhuma recorrencia com parametros informados"
  }
}

Recusa da autorização pelo pagador:

Caso seja decidido recusar a solicitação, não é necessário ter ação alguma, basta não aceitar que ela expirará no prazo máximo de 30 dias

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	Descrição	Tipo
id*	Identificador único da recorrencia	string
deniedReason	(motivo da recusa) ENUM(CREDIT_PARTY_IS_NOT_KNOWN,NOT_INTERESTED, NOT_OFFERED_TO_LEGAL_PERSON)	Enum
cancellingReason	Motivo do cancelamento ENUM(ACCOUNT_CANCELLATION,CREDIT_PARTY_END_OF_ACTIVITIES, PAYER_DEAD,CONFIRMATION_ERROR,FRAUD, CONFIRMED_IN_OTHER_JOURNEY,CREDIT_PARTY_REQUEST, DEBIT_PARTY_REQUEST,TIMEOUT)	Enum
status*	status da recorrência ENUM(PENDING_DEBIT_PARTY,PENDING_CREDIT_PARTY,CONFIRMED, CANCELLATION_REQUEST,CANCELLING,CANCELLED,EXPIRED,ERROR)	Enum
journeys*	Lista de jornadas requisitadas para a recorrencia	Array de objeto
interval*	Informações de intervalo da recorrência	objeto
frequencyType*	Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)	Enum
amount	Valor do pagamento recorrente	Decim
creditParty*	Dados do Recebedor	Objeto
debitParty*	Dados do pagador	Objeto
debtor	Pessoa ou empresa devedora.	Objeto
contract*	Dados do contrato associado à cobrança	Objeto
cancellation	Dados do cancelamento, se houver	Objeto
createDate*	Data de criação da recorrencia	string (ISO 8601)
updateDate	Data da última atualização	string (ISO 8601)
deleteDate	Data de exclusão, se houver	string (ISO 8601)
cancelledDate	Data em que foi cancelada.	string (ISO 8601)
allowsNewAttemptsAfterExpiration*	indica se terá retentativas de cobranças após a data de vencimento	Boolean
allowAutoSendingPaymentInstructions*	indica se terá valor variável ou fixo da recorrência, sendo valor fixo a Celcoin já realiza o envio automaticamente. Caso seja variável, o recebedor sempre nos enviará o valor a ser cobrado a cada ciclo.	Boolean
recurrencyMinAmount	Valor mínimo que o recebedor indica para o pagador, em casos de recorrências com valores variáveis. Exemplo conta de luz, recebedor diz que o mínimo para o pagador customizar o valor será de R$30,00. Então o Pagador só poderá customizar o valor máximo que seja maior ou igual a R$30,00.	Decimal

Objeto journey

Campo	Descrição	Tipo
status*	Status da jornada Enum(ACCEPTED,DENIED,PENDING,CANCELLING,CANCELLED)	Enum
type*	Versão do payload Enum ( ExternalInteration,QRCodeInteration,QRCodePaymentOpitionalInteration)	Enum
accepetedDate	Data em que foi aceita.	string (ISO 8601)
denyDate	Data em que foi negada.	string (ISO 8601)

Objeto Interval

Campo	Descrição	Tipo
start*	Início da recorrência.	string (ISO 8601)
end	Fim da recorrência..	string (ISO 8601)
frequencyType*	Frequência da recorrência Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)	Enum

Objeto CreditParty

Campo	Descrição	Tipo
taxId*	CNPJ do Recebedor	string
name*	Nome do recebedor	string
bank*	ISPB do banco recebedor	string

Objeto do DebitParty

Campo	Descrição	Tipo
personType*	Tipo de pessoa pagador ENUM(NATURAL_PERSON,LEGAL_PERSON)	Enum
taxId*	CPF/CNPJ do pagador	string
bank*	ISPB do banco	string
account*	numero da conta	string
branch	Agência	string
stateCode	Código de município do usuário pagador no IBGE.	string

Objeto debtor

Campo	Descrição	Tipo
personType*	Tipo de pessoa do devedor ENUM(NATURAL_PERSON,LEGAL_PERSON)	Enum
taxId*	CPF/CNPJ do devedor	string
nome*	nome do devedor	string

Objeto contract

Campo	Descrição	Tipo
number*	Número do contrato vinculado.	string
description	descrição do contrato	string

Objeto cancellation

Campo	Descrição	Tipo
id*	ID do cancelamento.	string
cancelledBy	Quem cancelou(credit = recebedor , debit = pagador) Enum( CREDIT,DEBIT)	Enum
personType	Tipo da pessoa que cancelou (PF ou PJ) ENUM(NATURAL_PERSON,LEGAL_PERSON)	Enum
taxId	CPF/CNPJ de quem cancelou	string
reason	Motivo do cancelamento ENUM(ACCOUNT_CANCELLATION, CREDIT_PARTY_END_OF_ACTIVITIES,PAYER_DEAD,CONFIRMATION_ERROR,FRAUD, CONFIRMED_IN_OTHER_JOURNEY,CREDIT_PARTY_REQUEST,DEBIT_PARTY_REQUEST,TIMEOUT)	Enum
date	Data do cancelamento	string (ISO 8601)

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

Updated 6 days ago