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


  1. Receber Webhook com a Solicitação de Recorrência (Evento: XX) - [API Reference]
  2. Exibir detalhes da solicitação ao cliente e coletar sua decisão (autorizar ou recusar)
    • Este passo é interno ao seu sistema.
  3. Realizar autenticação na API - [API Reference]
  4. 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]
  5. 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 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:

ValorDescrição
CREDIT_PARTY_IS_NOT_KNOWNO usuário pagador não reconhece o usuário recebedor ou não tem qualquer tipo de relacionamento ativo com ele.
NOT_INTERESTEDO 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_PERSONNão oferecido para pessoa jurídica.

Exemplo de resposta de Sucesso (revisar contrato)

Estrutura do JSON


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 do Pix Automático
amountdecimalValor do pagamento recorrente
creditParty*objetoDados do Recebedor
debitParty*objetoDados do pagador
debtorobjetoPessoa ou empresa devedora.
contract*Dados 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.


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
}