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/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)