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 evento: pix-automatic: 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"
},
"recurrencyAmountType":"FIXED"
"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": "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 evento: pix-automatic: nas recorrências com valor variável não será enviado o campo "amount", mas sim o campo "maxAmountRecurrency", além do campo "recurrencyAmountType" = variable, indicando que as transações terão valor variável todos os meses, como uma conta de luz.
{
"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"
},
"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": "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
}
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
{
"maxAmount": 100,
"debitParty": {
"name": "Fulano de tal",
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "13935893",
"branch":"0001",
"account": "12345-6",
"accountType": "CACC",
"stateCode": "SP"
},
}
cURL da chamada
curl -X 'PATCH' \
'https://sandbox.openfinance.celcoin.dev/baas/v2/automatic/recurrencies/authorization/{id}/accept' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"maxAmount": 100,
"debitParty": {
"name": "Fulano de tal",
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "13935893",
"branch":"0001",
"account": "12345-6",
"accountType": "CACC",
"stateCode": "SP"
},
}'
Exemplo de resposta de Sucesso
{
"status": 200,
"version": "1.0",
"body": {
"id": "RR0435879820240920njua7shf40o",
"deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN",
"cancellingReason": "ACCOUNT_CANCELLATION",
"status": "PENDING_CREDIT_PARTY",
"journeys": [
{
"status": "ACCEPTED",
"type": 1,
"accepetedDate": "2025-05-10T10:15:00Z",
"denyDate":null
}
],
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"frequencyType": "MONTHLY",
"amount": 50,
"creditParty": {
"taxId": "12345678000199",
"name": "Loja Virtual Ltda"
"bank":"13935893"
},
"debitParty": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "13935893",
"branch":"4444"
"branch":"0001",
"account": "12345-6",
"stateCode": "SP"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"name": "João da Silva"
},
"contract": {
"number": "CONTR-2025-PIX-001",
"description": "Assinatura mensal do plano premium"
},
"cancellation": null,
"createDate": "2025-05-01T08:00:00Z",
"updateDate": "2025-05-15T10:30:00Z",
"deleteDate": "2025-05-20T00:00:00Z",
"cancelledDate": "2025-05-16T15:03:07.709Z"
}
}
Tabela de apoio
Objeto body
Campo | Descrição | Tipo |
---|---|---|
id* | Identificador único da recorrencia | string |
deniedReason | (motivo da recusa) ENUM(CREDIT_PARTY_IS_NOT_KNOWN,NOT_INTERESTED, NOT_OFFERED_TO_LEGAL_PERSON) | Enum |
cancellingReason | 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 |
status* | status da recorrência ENUM(PENDING_DEBIT_PARTY,PENDING_CREDIT_PARTY,CONFIRMED, CANCELLATION_REQUEST,CANCELLING,CANCELLED,EXPIRED,ERROR) | Enum |
journeys* | Lista de jornadas requisitadas para a recorrencia | Array de objeto |
interval* | Informações de intervalo da recorrência | objeto |
frequencyType* | Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY) | Enum |
amount | Valor do pagamento recorrente | Decim |
creditParty* | Dados do Recebedor | Objeto |
debitParty* | Dados do pagador | Objeto |
debtor | Pessoa ou empresa devedora. | Objeto |
contract* | Dados do contrato associado à cobrança | Objeto |
cancellation | Dados do cancelamento, se houver | Objeto |
createDate* | Data de criação da recorrencia | string (ISO 8601) |
updateDate | Data da última atualização | string (ISO 8601) |
deleteDate | Data de exclusão, se houver | string (ISO 8601) |
cancelledDate | Data em que foi cancelada. | string (ISO 8601) |
allowsNewAttemptsAfterExpiration* | indica se terá retentativas de cobranças após a data de vencimento | Boolean |
allowAutoSendingPaymentInstructions* | indica se terá valor variável ou fixo da recorrência, sendo valor fixo a Celcoin já realiza o envio automaticamente. Caso seja variável, o recebedor sempre nos enviará o valor a ser cobrado a cada ciclo. | Boolean |
recurrencyMinAmount | Valor mínimo que o recebedor indica para o pagador, em casos de recorrências com valores variáveis. Exemplo conta de luz, recebedor diz que o mínimo para o pagador customizar o valor será de R$30,00. Então o Pagador só poderá customizar o valor máximo que seja maior ou igual a R$30,00. | Decimal |
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) |
Exemplo de resposta com erro
{
"status": 400,
"version": "v1.0.0",
"error": {
"errorCode": "CBE215",
"message": "Não foi encontrada nenhuma recorrencia com parametros informados"
}
}
Recusa:
PATCH /recurrencies/authorization/{id}/deny
Parâmetro: id
endpoint: recurrencies/authorization/{id}/deny
request:
{
"deniedReason": "CREDIT_PARTY_IS_NOT_KNOWN"
}
{
"status": 200,
"version": "1.0",
"body": {
"id": "RR0435879820240920njua7shf40o",
"deniedReason": "NOT_INTERESTED",
"cancellingReason": NULL,
"status": "PENDING_CREDIT_PARTY",
"journeys": [
{
"status": "DENIED",
"type": 1,
"accepetedDate":NULL,
"denyDate": "2025-05-10T10:15:00Z"
}
],
"interval": {
"start": "2025-06-01T00:00:00Z",
"end": "2025-12-01T00:00:00Z",
"frequencyType": "MONTHLY"
},
"frequencyType": "MONTHLY",
"amount": 50,
"creditParty": {
"taxId": "12345678000199",
"name": "Loja Virtual Ltda"
"bank":"13935893"
},
"debitParty": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"bank": "13935893",
"branch":"4444",
"account": "123456",
"stateCode": "2700805"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"name": "João da Silva"
},
"contract": {
"number": "CONTR-2025-PIX-001",
"description": "Assinatura mensal do plano premium"
},
"cancellation": null,
"createDate": "2025-05-01T08:00:00Z",
"updateDate": "2025-05-15T10:30:00Z",
"deleteDate": "2025-05-20T00:00:00Z",
"cancelledDate": "2025-05-16T15:03:07.709Z"
}
}
Exemplo de resposta com erro
{
"status": 400,
"version": "v1.0.0",
"error": {
"errorCode": "CBE215",
"message": "Não foi encontrada nenhuma recorrencia com parametros informados"
}
}
Se o pagador optar por recusar uma autorização de recorrência do recebedor, é necessário informar o motivo.
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. |
Regras importantes desta etapa:
A decisão deve ser registrada antes da data de expiração da proposta.
A recorrência não pode ser alterada pelo pagador (dados como valor, datas e periodicidade são fixos).
Se o usuário não responder dentro do prazo, a autorização será automaticamente marcada como expirada e removida da lista de pendências.
Depois que o usuário tomar a decisão e a Celcoin registrar junto ao PSP recebedor será enviado um webhook para notificar o status final da autorização.
Modelos de Webhook
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 Valor variável:
Status: CONFIRMED
evento: pix-automatic
{
"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"
},
"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": null,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": "2025-05-10T09:10:00Z",
"denyDate": null,
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
Exemplo de Contrato do Webhook de Confirmação Final Valor fixo:
Status: CONFIRMED
evento: pix-automatic
{
"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"
},
"recurrencyAmountType":"FIXED",
"amount":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": null,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": "2025-05-10T09:10:00Z",
"denyDate": null,
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
Webhook Status: DENIED rejeição da autorização com valor fixo
evento :pix-automatic
{
"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": {
"id": "IC1234567820250516abcdefghi",
"cancelledBy": "DEBIT",
"personType": "NATURAL_PERSON",
"taxId": "98765432100",
"reason": "ACCOUNT_CANCELLATION",
"date": "2025-05-16T15:30:00Z"
},
"error": {
"code": "E402",
"description": "Falha ao registrar a autorização automática no PSP recebedor"
},
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": null,
"denyDate": "2025-05-10T09:10:00Z",
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
Webhook Status: DENIED rejeição da autorização com valor variável
evento :pix-automatic
{
"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"
},
"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": null,
"createDate": "2025-05-10T09:00:00Z",
"acceptanceDate": null,
"denyDate": "2025-05-10T09:10:00Z",
"updateDate": "2025-05-16T10:00:00Z",
"deleteDate": null
}
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