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 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

CampoDescriçãoTipo
id*Identificador único da recorrenciastring
deniedReason(motivo da recusa)
ENUM(CREDIT_PARTY_IS_NOT_KNOWN,NOT_INTERESTED,
NOT_OFFERED_TO_LEGAL_PERSON)
Enum
cancellingReasonMotivo 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 recorrenciaArray de objeto
interval*Informações de intervalo da recorrênciaobjeto
frequencyType* Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)Enum
amountValor do pagamento recorrenteDecim
creditParty*Dados do RecebedorObjeto
debitParty*Dados do pagadorObjeto
debtorPessoa ou empresa devedora.Objeto
contract*Dados do contrato associado à cobrançaObjeto
cancellationDados do cancelamento, se houverObjeto
createDate*Data de criação da recorrenciastring (ISO 8601)
updateDateData da última atualizaçãostring (ISO 8601)
deleteDateData de exclusão, se houverstring (ISO 8601)
cancelledDateData em que foi cancelada.string (ISO 8601)
allowsNewAttemptsAfterExpiration*indica se terá retentativas de cobranças após a data de vencimentoBoolean
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
recurrencyMinAmountValor 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


CampoDescriçãoTipo
status*Status da jornada
Enum(ACCEPTED,DENIED,PENDING,CANCELLING,CANCELLED)
Enum
type*Versão do payload
Enum ( ExternalInteration,QRCodeInteration,QRCodePaymentOpitionalInteration)
Enum
accepetedDateData em que foi aceita.string (ISO 8601)
denyDateData em que foi negada.string (ISO 8601)

Objeto Interval


CampoDescriçãoTipo
start*Início da recorrência.string (ISO 8601)
endFim da recorrência..string (ISO 8601)
frequencyType*Frequência da recorrência
Enum( WEEKLY,MONTHLY,QUARTER,SEMESTER,YEARLY)
Enum

Objeto CreditParty


CampoDescriçãoTipo
taxId*CNPJ do Recebedorstring
name*Nome do recebedorstring
bank*ISPB do banco recebedorstring

Objeto do DebitParty


CampoDescriçãoTipo
personType*Tipo de pessoa pagador
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxId*CPF/CNPJ do pagadorstring
bank*ISPB do banco string
account*numero da contastring
branchAgênciastring
stateCodeCódigo de município do usuário pagador no IBGE.string

Objeto debtor


CampoDescriçãoTipo
personType*Tipo de pessoa do devedor
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxId*CPF/CNPJ do devedorstring
nome*nome do devedorstring

Objeto contract


CampoDescriçãoTipo
number*Número do contrato vinculado.string
descriptiondescrição do contratostring

Objeto cancellation


CampoDescriçãoTipo
id*ID do cancelamento.string
cancelledByQuem cancelou(credit = recebedor , debit = pagador)
Enum( CREDIT,DEBIT)
Enum
personTypeTipo da pessoa que cancelou (PF ou PJ)
ENUM(NATURAL_PERSON,LEGAL_PERSON)
Enum
taxIdCPF/CNPJ de quem canceloustring
reasonMotivo 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
dateData do cancelamentostring (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:

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.

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.