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:

• 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/baas/v2/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/baas/v2/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:

Exemplo de resposta de Sucesso (revisar contrato)

Estrutura do JSON

Estrutura do JSON

Estrutura do objeto Body

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
}

❗️

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.