Autorização - Jornada 4
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:
- Se autorizado pelo cliente: Enviar a autorização da recorrência - [API Reference]
ou - Se recusado pelo cliente: Enviar a recusa da recorrência - [API Reference]
- 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) - [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/full
{
"emv": "00020101021226990014br.gov.bcb.pix2577qr-h.sandbox.pix.bcb.gov.br/rest/api/v2/cobv/91da736cbcd648f1af4ecd86e293069b5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80950014br.gov.bcb.pix2573qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/b2766ea464584662957022aa9de45dc06304D485"
}
Resposta
{
"version": "1.0.0",
"status": 200,
"body": {
"type": "DUEDATE_COMPOSED",
"merchantAccountInformation": {
"url": "qr-h.sandbox.pix.bcb.gov.br/rest/api/v2/cobv/91da736cbcd648f1af4ecd86e293069b",
"gui": "br.gov.bcb.pix",
"merchantCategoryCode": "0000",
"additionaldata": null,
"withdrawalServiceProvider": null,
"merchantName": "Pix Tester 99999918",
"merchantCity": "BRASILIA",
"postalCode": "70074900"
},
"key": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219",
"amount": {
"original": 533.27,
"abatement": 0,
"discount": 0,
"interest": 0,
"final": 533.27,
"fine": 0,
"canModifyFinalAmount": false,
"withdrawal": null,
"change": null
},
"transactionIdentification": "91da736cbcd648f1af4ecd86e293069b",
"payload": {
"status": "ACTIVE",
"revision": 0,
"calendar": {
"createdAt": "2025-07-22T06:41:17.041Z",
"presentation": "2025-07-22T09:41:38.525Z",
"dueDate": "2025-08-01T00:00:00",
"validateAfterDuedate": 30,
"expiration": null,
"expirationDate": "2025-08-31T00:00:00"
},
"debtor": {
"cpf": "30286340402",
"cnpj": null,
"name": "Fulano de Tal"
},
"receiver": {
"cnpj": "99999918999924",
"cpf": null,
"fantasyName": null,
"publicArea": "Setor Bancario Sul SBS Quadra 3 Bloco B Ed Sede",
"city": "BRASILIA",
"state": "DF",
"postalCode": "70074900"
},
"payerQuestion": null,
"additionalInformation": null
},
"recorrency": {
"journeyType": 4,
"idRecorrencia": "RR999999182025072205342405676",
"interval": {
"start": "2025-07-22",
"end": null,
"frequencyType": "MONTHLY"
},
"amount": 992.73,
"recurrencyMaxAmount": 0,
"recurrencyAmountType": "FIXED",
"creditParty": {
"bank": "99999918",
"taxId": "99999918999924",
"name": "Pix Tester 918"
},
"debtor": {
"taxId": "13935893000109",
"name": "INTEGRATED SOLUTIONS TO BUSINE",
"personType": "LEGAL_PERSON"
},
"contract": {
"number": "21749160",
"description": "Serviço de Segurança"
}
}
}
}
Na resposta o qrcode terá o type DUEDATE_COMPOSED
Após identificar o qrcode como qrcode de Jornada 4 deve exibir essas informações ao usuário pagador.
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).
Após a exibição dos dados do QR Code, deve ser realizado o pagamento da cobrança como no fluxo usual de pagamento de QR Code Dinâmico.
Aceitar a recorrência via API
Na sequência, apresenta-se a recorrência ao cliente. Caso ele aceite, deve-se utilizar o endpoint
POST /recurrencies/authorization/accept
Para aceitar a recorrência.
{
"id": "RR999999182025071156891899276",
"endToEnd": "E13935893202507220953jTc4IRhQyZ9",
"journeyType": 4,
"interval": {
"start": "2025-07-22",
"end": null,
"frequencyType": "MONTHLY"
},
"amount": 992.73,
"recurrencyMaxAmount": null,
"recurrencyAmountType": "FIXED",
"creditParty": {
"bank": "99999918",
"taxId": "99999918999924",
"name": "Pix Tester 918"
},
"debitParty": {
"name": "Blanca Fritsch",
"personType": "NATURAL_PERSON",
"taxId": "46128231845",
"bank": "13935893",
"branch": "0001",
"account": "4171740",
"accountType": "CACC",
"stateCode": "0"
},
"debtor": {
"taxId": "13935893000109",
"name": "INTEGRATED SOLUTIONS TO BUSINE",
"personType": "LEGAL_PERSON"
},
"contract": {
"number": "21749160",
"description": "Serviço de Segurança"
}
}
Caso o usuário aceite a recorrência, será disparado um webhook para seu sistema com o status da recorrência atualizado após a liquidação do pagamento:
{
"id": "RR1234567820250516abcdefghi",
"deniedReason": null,
"status": "CONFIRMED",
"journey": {
"status": "ACCEPTED",
"type": 4
},
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"recurrencyAmountType":"VARIABLE"
"recurrencyMaxAmount":100.00
"creditParty": {
"taxId": "12345678000199",
"bank": "0000000",
"name": "Academia Fitness Pro"
},
"debitParty": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "0000000",
"account": "98765-4",
"branch":"0001",
"stateCode": "SP"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"name": "Carlos Eduardo Oliveira"
},
"contract": {
"number": "CTR-PIX-2025-001",
"description": "Plano anual academia com acesso ilimitado"
},
"cancellation":null,
"error": nu,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": "2025-05-10T09:10:00Z",
"denyDate": null,
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
Recusa da autorização da recorrência:
Caso o pagador não deseja aceitar a autorização de recorrência, basta apenas não fazer o aceite nem o pagamento imediato dela, e em até 30 dias essa autorização se expirará automaticamente
Tabela de apoio.
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* | objeto | 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. |
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) |
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