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

  1. Cliente inicia um pagamento e realiza a leitura de um QR Code (Passo no seu sistema).
  2. Realizar autenticação na API (para decodificação do QR Code) - [API Reference]
  3. Realizar a decodificação/consulta dos dados do QR Code via API - [API Reference]
  4. Exibir os detalhes do pagamento ao cliente para confirmação (Passo no seu sistema).
  5. Cliente confirma a intenção de realizar o pagamento (Passo no seu sistema).
  6. Realizar o pagamento do QR Code via API - [API Reference]
  7. Receber Webhook com o status do pagamento (Evento: XX)

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

  1. 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).
  2. Cliente analisa a oferta e decide se aceita ou recusa a autorização do Pix Automático (Passo no seu sistema).
  3. 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]
  4. 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:



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

CampoTipoDescrição
statusintCódigo de status da resposta.
versionstringVersão do payload.
bodyobjectDados principais do recurso.

Estrutura do objeto Body

CampoTipoDescrição
id*stringIdentificador único da recorrencia
deniedReasonENUM (CREDIT_PARTY_IS_NOT_KNOWN, NOT_INTERESTED, NOT_OFFERED_TO_LEGAL_PERSON)Motivo da recusa, se aplicável.
cancellingReasonENUM (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 objetosLista de jornadas requisitadas para a recorrencia
interval*objetoInformações de intervalo da recorrência
frequencyType*Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)Frequência da recorrência
amountdecimalValor do pagamento recorrente
creditParty*objetoDados do Recebedor
debitParty*objetoDados do pagador
debtorobjetoPessoa ou empresa devedora.
contract*objetoDados do contrato associado à cobrança
cancellationobjetoDados do cancelamento, se houver
createDate*string (ISO 8601)Data de criação da recorrencia
updateDatestring (ISO 8601)Data da última atualização
deleteDatestring (ISO 8601)Data de exclusão, se houver
cancelledDatestring (ISO 8601)Data em que foi cancelada.


Objeto journey

CampoDescriçãoTipo
status*Status da jornada
Enum(ACCEPTED,DENIED,PENDING,CANCELLING,CANCELLED)
Enum
type*Versão do payload
Enum ( ExternalInteration,QRCodeInteration,QRCodePaymentOpitionalInteration)
Enum
accepetedDateData em que foi aceita.string (ISO 8601)
denyDateData em que foi negada.string (ISO 8601)

Objeto Interval


CampoDescriçãoTipo
start*Início da recorrência.string (ISO 8601)
endFim da recorrência..string (ISO 8601)
frequencyType*Frequência da recorrência
Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)
Enum

Objeto CreditParty


CampoDescriçãoTipo
taxId*CNPJ do Recebedorstring
name*Nome do recebedorstring
bank*ISPB do banco recebedorstring

Objeto do DebitParty


CampoDescriçãoTipo
personType*Tipo de pessoa pagador
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxId*CPF/CNPJ do pagadorstring
bank*ISPB do banco string
account*numero da contastring
branchAgênciastring
stateCodeCódigo de município do usuário pagador no IBGE.string

Objeto debtor


CampoDescriçãoTipo
personType*Tipo de pessoa do devedor
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxId*CPF/CNPJ do devedorstring
nome*nome do devedorstring

Objeto contract


CampoDescriçãoTipo
number*Número do contrato vinculado.string
descriptiondescrição do contratostring

Objeto cancellation


CampoDescriçãoTipo
id*ID do cancelamento.string
cancelledByQuem cancelou(credit = recebedor , debit = pagador)
Enum( CREDIT,DEBIT)
Enum
personTypeTipo da pessoa que cancelou (PF ou PJ)
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxIdCPF/CNPJ de quem canceloustring
reasonMotivo 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
dateData do cancelamentostring (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.