Autorização - Jornada 3

Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

Nesta jornada, o usuário pagador inicia a experiência ao escanear um QR Code que contém duas informações integradas: uma cobrança Pix imediata, a ser paga no momento da leitura, e os dados da recorrência do Pix Automático, que definem as condições de pagamento para cobranças futuras.

O ponto central desta jornada é que o pagamento da cobrança imediata implica automaticamente a aceitação do Pix Automático como forma de pagamento para as cobranças subsequentes.

Na Jornada 3, de forma resumida, o aceite ao Pix Automático é obrigatório caso o cliente pague o Qr Code (diferente da Jornada 4, que é opcional).

🚧
Importante
Caso o usuário não concorde com as condições da recorrência, o pagamento não poderá ser realizado.

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 e as informações de pagamento (obtidos via API) ao cliente (Passo no seu sistema).
Cliente decide prosseguir com o pagamento. (Ao confirmar o pagamento, o cliente também aceitará automaticamente a recorrência vinculada) (Passo no seu sistema).
Realizar o pagamento do QR Code via API - [API Reference]
Receber Webhook com o status do pagamento (Evento: XX)
Se o pagamento for liquidado: Receber Webhook com a confirmação e os detalhes da recorrência estabelecida (Evento:

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

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": "5",
    "collection": "1",
    "payloadFormatIndicator": "02",
    "merchantAccountInformation": {
        "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/0513bd598a59239884b9fbb9b5e788",
        "gui": "br.gov.bcb.pix",
        "key": "[email protected]",
        "additionalInformation": null,
        "withdrawalServiceProvider": "00000000"
    },
    "merchantCategoryCode": 0,
    "transactionCurrency": 0,
    "transactionAmount": 20.00,
    "countryCode": null,
    "merchantName": "Fulano de Ta teste",
    "merchantCity": "Barueri",
    "postalCode": null,
    "initiationMethod": null,
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000242504",
    "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 5

Exemplo /emv/full

{
    "emv": "00020101021226940014br.gov.bcb.pix2572qr-h.sandbox.pix.bcb.gov.br/rest/api/v2/6200770704454492b187705eba48de685204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80950014br.gov.bcb.pix2573qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/0347dc5bd48f4b31a1860c3b6a7065b063044B4E"
}

Resposta

{
    "version": "1.0.0",
    "status": 200,
    "body": {
        "type": "IMMEDIATE_COMPOSED",
        "merchantAccountInformation": {
            "url": "qr-h.sandbox.pix.bcb.gov.br/rest/api/v2/6200770704454492b187705eba48de68",
            "gui": "br.gov.bcb.pix",
            "merchantCategoryCode": "0000",
            "additionaldata": null,
            "withdrawalServiceProvider": null,
            "merchantName": "Pix Tester 99999918",
            "merchantCity": "BRASILIA",
            "postalCode": null
        },
        "key": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219",
        "amount": {
            "original": 584.71,
            "abatement": null,
            "discount": null,
            "interest": null,
            "final": 584.71,
            "fine": null,
            "canModifyFinalAmount": false,
            "withdrawal": null,
            "change": null
        },
        "transactionIdentification": "6200770704454492b187705eba48de68",
        "payload": {
            "status": "ACTIVE",
            "revision": 0,
            "calendar": {
                "createdAt": "2025-07-18T18:22:27.774Z",
                "presentation": "2025-07-18T18:22:44.737Z",
                "dueDate": null,
                "validateAfterDuedate": null,
                "expiration": 86400,
                "expirationDate": "2025-07-19T18:22:27.774Z"
            },
            "debtor": {
                "cpf": "33241646130",
                "cnpj": null,
                "name": "Fulano de Tal"
            },
            "receiver": null,
            "payerQuestion": null,
            "additionalInformation": [
                {
                    "value": "Residencial",
                    "key": "Entrega"
                }
            ]
        },
        "recorrency": {
            "journeyType": 3,
            "idRecorrencia": "RR999999182025071841111672931",
            "interval": {
                "start": "2025-07-18",
                "end": null,
                "frequencyType": "MONTHLY"
            },
            "amount": 321.52,
            "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": "85092252",
                "description": "Serviço de Segurança"
            }
        }
    }
}

Na resposta o Qr Code terá o type IMMEDIATE_COMPOSED

Após identificar o Qr Code como Qr Code de Jornada 3 deve-se exibir essas informações ao usuário pagador.

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

Após a exibição dos dados do QR Code, o objeto de recorrência, que foi obtido a partir da decodificação do QR Code, deve ser enviado ao endpoint de pagamento. No processo, será apresentado ao usuário um campo para confirmar a aceitação da recorrência, representado pelo campo recurrencyAccept. Se o usuário optar por não aceitar a recorrência (quando recurrencyAccept for falso), o pagamento será interrompido e não prosseguirá. No entanto, se a aceitação for confirmada (quando recurrencyAccept for verdadeiro), o pagamento imediato será processado.Deve ser repassado os dados da recorrência obtidos na decodificação do qrcode.

Exemplo POST /pix/payment

{
    "amount": 584.71,
    "clientCode": "{{$guid}}",
    "debitParty": {
        "account": "4171740"
    },
    "endToEndId": "E139358932025071818222NYE7gQVL3C",
    "creditParty": {
        "taxId": "99999918999924",
        "bank": "99999918",
        "account": "121212",
        "branch": "1235",
        "name": "teste",
        "accountType": "TRAN",
        "personType": "NATURAL_PERSON",
        "key": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219"
    },
    "initiationType": "DYNAMIC_QRCODE",
    "transactionIdentification": "6200770704454492b187705eba48de68",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "transactionType": "TRANSFER",
    "recurrencyAccept": true,
    "recurrency": {
        "recurrencyId": "RR999999182025071841111672931",
        "journeyType": 3,
        "interval": {
            "start": "2025-07-18",
            "end": null,
            "frequencyType": "MONTHLY"
        },
        "amount": 321.52,
        "recurrencyMaxAmount": 0,
        "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"
        },
        "contract": {
            "number": "85092252",
            "description": "Serviço de Segurança"
        }
    }
}

Exemplo de resposta

{
    "status": "PROCESSING",
    "version": "1.0.0",
    "body": {
        "id": "81c83a3e-728e-48e5-a8b9-3459d1cb1c79",
        "amount": 584.71,
        "clientCode": "bb877108-657a-4c39-aec6-e836a9cc25af",
        "transactionIdentification": "6200770704454492b187705eba48de68",
        "endToEndId": "E139358932025071818222NYE7gQVL3C",
        "initiationType": "DYNAMIC_QRCODE",
        "paymentType": "IMMEDIATE",
        "urgency": "HIGH",
        "transactionType": "TRANSFER",
        "debitParty": {
            "account": "4171740",
            "branch": "0001",
            "taxId": "46128231845",
            "name": "Blanca Fritsch",
            "accountType": "TRAN"
        },
        "creditParty": {
            "bank": "99999918",
            "key": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219",
            "account": "121212",
            "branch": "1235",
            "taxId": "99999918999924",
            "name": "teste",
            "accountType": "TRAN"
        },
        "remittanceInformation": null,
        "recurrencyAccept": true,
        "recurrency": {
            "journeyType": 3,
            "interval": {
                "start": "2025-07-18T00:00:00",
                "end": null,
                "frequencyType": "MONTHLY"
            },
            "recurrencyAmountType": "FIXED",
            "amount": 321.52,
            "recurrencyMaxAmount": 0,
            "maxValueFloor": null,
            "creditParty": {
                "taxId": "99999918999924",
                "name": "Pix Tester 918",
                "bank": "99999918"
            },
            "debitParty": {
                "name": "Blanca Fritsch",
                "taxId": "46128231845",
                "bank": "13935893",
                "branch": "0001",
                "account": "4171740",
                "accountType": "CACC",
                "stateCode": "0",
                "maxAmount": null
            },
            "debtor": {
                "taxId": "13935893000109",
                "name": "INTEGRATED SOLUTIONS TO BUSINE"
            },
            "contract": {
                "number": "85092252",
                "description": "Serviço de Segurança"
            }
        },
        "taxIdPaymentInitiator": null
    }
}

O pagamento imediato precisa ser liquidado com sucesso antes de prosseguir com a autorização do Pix Automático para as cobranças futuras. Ou seja, a autorização do Pix Automático só acontecerá após a confirmação e finalização do pagamento imediato.

Se o pagamento for liquidado com sucesso, será disparado um webhook para seu sistema com o status da recorrência atualizado, indicando que o cliente realizou o pagamento imediato e aderiu ao pix automático para futuras cobranças.

Exemplo de webhook de autorização aceita

{
  "id": "RR1234567820250516abcdefghi",
  "deniedReason": null,
  "status": "CONFIRMED",
  "journey": {
    "status": "ACCEPTED",
    "type": 3
  },
  "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 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

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*		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 22 hours ago

Autorização - Jornada 3

Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

🚧
Importante

Passos para Integrar

Fluxo de Integração

Consulta de QR Code EMV

Exibição da Solicitação e Coleta da Decisão do Cliente Final 🙋‍♂️❓

Essa exibição deve incluir:

Exemplo POST /pix/payment

Recusa da recorrência.

❗️
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.

Jornada 3 : Autorização com QR Code contendo cobrança imediata e dados da recorrência

🚧Importante

Passos para Integrar

Fluxo de Integração

Consulta de QR Code EMV

Exibição da Solicitação e Coleta da Decisão do Cliente Final 🙋‍♂️❓

Essa exibição deve incluir:

Exemplo POST /pix/payment

Recusa da recorrência.

❗️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.

🚧
Importante

❗️
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.