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:
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]
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 6 days ago