Autorização - Jornada 1
Jornadas 1
Jornada 1 : jornada de autorização sem QR Code, com notificação via app para confirmação
Na Jornada 1, o pagador informa diretamente ao recebedor que deseja aderir ao Pix Automático através de uma notificação.
O PSP recebedor envia uma solicitação de autorização para o PSP pagador, que precisa ser validada, exibida ao usuário final e respondida (aceitando ou recusando).
Quando o PSP recebedor inicia a solicitação, a Celcoin receberá o pedido com os dados da recorrência.
Após a Celcoin validar os dados da solicitação de recorrência recebida do PSP recebedor (etapas anteriores), os dados validados da proposta serão enviados via webhook para o sistema do cliente, que é responsável por exibir essas informações ao usuário pagador. Nesse momento a autorização estará com status

Passos para Integrar
- Receber Webhook com a Solicitação de Recorrência (Evento: XX) - [API Reference]
- Exibir detalhes da solicitação ao cliente e coletar sua decisão (autorizar ou recusar)
- Este passo é interno ao seu sistema.
- Realizar autenticação na API - [API Reference]
- 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 da recorrência por ID - [API Reference]
Fluxo para aceitar solicitação de recorrência da jornada 1

Fluxo para recusar solicitação de recorrência da jornada 1

Recebimento da Notificação de Solicitação de Autorização (Webhook) 🔔
Assim que uma nova solicitação de autorização for criada em nosso sistema, enviaremos automaticamente um webhook para o endpoint que você configurou. Este webhook conterá todas as informações necessárias sobre a solicitação para que você possa processá-la.
O que você precisa fazer:
- Configure um endpoint em seu sistema para receber nossas notificações via webhook.
- Garanta que seu sistema consiga processar o JSON enviado no corpo (body) do webhook.
Exemplo de Contrato do Webhook (Payload) - Recorrência com valor fixo:: nas recorrências com valor fixo, somente será enviado o campo "amount", como o caso de um serviço de streaming, que todos os meses é o mesmo valor.
{
"id": "RR1234567820250516abcdefghi",
"deniedReason":null,
"status": "PENDING_DEBIT_PARTY",
"journey": {
"status": "PENDING",
"type": 1
},
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"amount": 150.50,//sempre será neste valor a recorrência do Pix Automático
"creditParty": {
"taxId": "12345678000199",
"bank": "0000000",
"name": "Academia Fitness Pro"
},
"debitParty": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "0000000",
"account": "98765-4",
"branch":"0001",
"stateCode": "00000"
},
"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": null,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": null,
"denyDate": null,
"updateDate":null,
"deleteDate": null
}
Exemplo de Contrato do Webhook (Payload) - Recorrência com valor variável:: nas recorrências com valor variável não será enviado o campo "amount", mas sim o campo "maxAmountRecurrency", indicando que as transações terão valor variável todos os meses, como uma conta de luz.
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 recusar 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.
- Enviar essa decisão para a Celcoin utilizando um dos endpoints dedicados:
Envio da Resposta da Autorização via API 🚀
Aceite -
Para recorrência de valor fixo, enviar como maxAmout o valor que foi previamente fornecido pela Celcoin no campo "Amount".
Para casos de cobrança variável, informar o valor que o próprio cliente desejar como sendo o "teto" para que aquela cobrança ocorra com sucesso. O envio deste campo é obrigatório em todos os casos de uso:
PATCH: /recurrencies/authorization/{id}/accept
Parâmetro: id
cURL da chamada
curl -X 'PATCH' \
'https://sandbox.openfinance.celcoin.dev/recurrencies/authorization/{id}/accept' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"maxAmount": 250
}'
Exemplo de resposta de Sucesso
Recusa:
PATCH /recurrencies/authorization/{id}/deny
Parâmetro: id
curl -X 'PATCH' \
'https://sandbox.openfinance.celcoin.dev/recurrencies/authorization/RR1234567820250516abcdefghi/deny' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN"
}'
Tipos de motivos de rejeição:
Valor | Descrição |
---|---|
CREDIT_PARTY_IS_NOT_KNOWN | O usuário pagador não reconhece o usuário recebedor ou não tem qualquer tipo de relacionamento ativo com ele. |
NOT_INTERESTED | O usuário pagador não tem interesse no uso do Pix Automático para pagar as cobranças referentes àquele usuário recebedor. |
NOT_OFFERED_TO_LEGAL_PERSON | Não oferecido para pessoa jurídica. |
Exemplo de resposta de Sucesso (revisar contrato)
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 | 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 do Pix Automático |
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. |
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: CONFIRMED
{
"id": "RR1234567820250516abcdefghi",
"deniedReason": null,
"status": "CONFIRMED",
"journey": {
"status": "ACCEPTED",
"type": 1
},
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"amount": 150.50,
"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
}
Status: DENIED
{
"id": "RR1234567820250516abcdefghi",
"deniedReason": "NOT_INTERESTED",
"status": "CANCELLED",
"journey": {
"status": "DENIED",
"type": 1
},
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"amount": 150.50,
"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": null,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": null,
"denyDate": "2025-05-10T09:10:00Z",
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
Updated 1 day ago