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:
- 6.1. Se autorizado pelo cliente: Enviar a autorização da recorrência - API Reference]
ou - 6.2. Se recusado pelo cliente: Enviar a recusa da recorrência - [API Reference]
- 6.1. Se autorizado pelo cliente: Enviar a autorização 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
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"
}
}
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.
Updated about 21 hours ago