Autorização - Jornada 1
Envio de notificação para o cliente pagador aderir ao Pix Automático
Caso de uso: A Jornada 1 foi pensada para casos de uso fora do ambiente Pix, como um envio de solicitação de adesão ao cliente pelo WhatsApp, por exemplo.
Caso o cliente em fluxo de WhatsAPP demonstre interesse em aderir a Jornada de Pix Automático, será enviado para ele através da Jornada 1 de Autorização, uma notificação diretamente no seu aplicativo bancário para adesão ao Pix Automático.
Este envio de notificação por parte do cliente recebedor diretamente ao banco do cliente pagador é a jornada 1 de autorização.
Neste fluxo, não há leitura de Qr Code Pix por parte do cliente pagador.
A empresa recebedora enviará os dados para o cliente pagador a partir das suas informações de CPF, Banco, Agência e Conta.
Neste fluxo, é possível que a oferta de Pix Automático seja por valor fixo (igual em todas as cobranças futuras por Pix Automático) ou por valor variável. Importante que no caso de cobranças com valor variável, o cliente pagador sempre irá definir um valor máximo (teto) para que os agendamentos sejam realizados.
Se no momento do consentimento de uma conta de luz o usuário pagador determine, por exemplo, que o valor máximo que ele deseja pagar através de Pix Automático é de R$ 200,00, em qualquer mês que a empresa recebedora tentar enviar uma ordem de valor máximo acima de R$ 200,00, essa cobrança de Pix Automático será rejeitada pelo banco do cliente pagador, que deverá pagar sua fatura de outra forma, manualmente.
Nos casos onde o valor enviado de uma cobrança é superior ao valor máximo definido pelo cliente, somente o agendamento daquela cobrança específica não ocorrerá, porém o consentimento de Pix Automático continuará ativo para todas as cobranças futuras, até que o cliente pagador cancele o consentimento em si.
Para adesões de Pix Automático através da Jornada 1, não existe fluxo de pagamento realizado na hora, somente a adesão para cobranças futuras.
Passos para Integrar
- Cliente final solicita a criação de uma recorrência.
- Realizar autenticação na API - [API Reference]
- Solicita a criação de recorrência da Jornada 1 - [Reference]
- Encaminha webhook com a confirmação do recebimento da solicitação.
- Encaminha webhook com a resposta da solicitação (Confirmação ou Negação)
Fluxo de integração - Jornada 1 - Autorização da Recorrência
Criação de recorrencia com valor fixo
JSON de Exemplo
Método: POST
/recurrencies/journey1
Body
{
"recurrencyId": "RR3606095020250712ObmNYRB9dYH",
"recurrency": {
"clientRequestId": "70db791c-f460-4656-8593-975d8cf9d055",
"amount": 10,
"interval": {
"start": "2025-07-11 ",
"end": "2025-07-11 ",
"frequencyType": "MONTHLY"
},
"creditParty": {
"branch": "0001",
"account": "123456",
"taxId": "string",
"name": "Empresa teste"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "12345678000101",
"name": "Fulano da Silva"
},
"contract": {
"number": "CONTRATO_ABC_001",
"description": "Servi�os de Assinatura Mensal"
},
"allowsNewAttemptsAfterExpiration": true,
"allowAutoSendingPaymentInstructions": false,
"debitParty": {
"personType": "LEGAL_PERSON",
"taxId": "12345678000101",
"bank": "stringst",
"branch": "0001",
"account": "string"
}
}
}
cURL da chamada
curl --location POST 'https://sandbox.openfinance.celcoin.dev/baas/v2/automatic/recurrencies/journey' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Token}}' \
--data '{
"recurrency": {
"clientRequestId": "a0574329-125f-41bf-9117-fb873421607b",
"interval": {
"start": "2025-07-07",
"end":"2026-07-07",
"frequencyType": "WEEKLY"
},
"amount": 200,
"creditParty": {
"branch": "1234",
"account": "1234567",
"taxId": "01234567000189",
"name": "Comércio Digital Ltda."
},
"debitParty": {
"bank": "12345678",
"personType": "LEGAL_PERSON",
"branch": "1234",
"account": "1234567",
"taxId": "01234567000189"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "09876543000121",
"name": "Pague Tudo Serviços S.A."
},
"contract": {
"number": "CONTRATO-2025-ABCD",
"description": "Assinatura mensal de plataforma"
},
"allowsNewAttemptsAfterExpiration": true,
"allowAutoSendingPaymentInstructions": true
}
}'
Exemplo de retorno
Sucesso 200
{
"status": 200,
"version": "1.0.0",
"body": {
"recurrencyId": "RR13935893202509052bkIbRX8GAb",
"clientRequestId": "61175601-c477-4b80-b91f-e306ead49fc4",
"interval": {
"start": "2025-09-05",
"end": "2025-09-07",
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-09-05T18:44:58.0638537Z"
}
],
"amount": 1,
"recurrencyMinAmount": null,
"creditParty": {
"bank": "13935893",
"taxId": "66335509000101",
"name": "Celcoin Instituição de Pagamento",
"branch": "0001",
"account": "4201455"
},
"debitParty": {
"personType": "NATURAL_PERSON",
"taxId": "11727388070",
"bank": "12345678",
"account": "4180030",
"branch": "0001"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "22698938080",
"name": "MOCK EXPIRED"
},
"contract": {
"number": "CONTRACT_cc639c46",
"description": "Assinatura Valida Teste"
},
"cancellation": null,
"createDate": "2025-09-05T18:44:58.0638537Z",
"acceptanceDate": null,
"denyDate": null,
"updateDate": null
}
}
Error 400
{
"status": 100,
"version": "string",
"error": {
"errorCode": "string",
"message": "string"
}
}
Criação de recorrência com valor variável
JSON de Exemplo: Método: POST /recurrencies/journey1
quando a recorrência é de valor variável, será preenchida a variável "recurrencyMinAmount", para poder indicar qual o mínimo que o pagador poderá customizar do valor máximo.
body
{
"recurrencyId": "RR3606095020250712ObmNYRB9dYH",
"recurrency": {
"clientRequestId": "70db791c-f460-4656-8593-975d8cf9d055",
"amount": 10,
"recurrencyMinAmount": 10,
"interval": {
"start": "2025-07-11 ",
"end": "2025-07-11 ",
"frequencyType": "MONTHLY"
},
"creditParty": {
"branch": "0001",
"account": "123456",
"taxId": "string",
"name": "Empresa teste"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "12345678000101",
"name": "Fulano da Silva"
},
"contract": {
"number": "CONTRATO_ABC_001",
"description": "Servicos de Assinatura Mensal"
},
"allowsNewAttemptsAfterExpiration": true,
"allowAutoSendingPaymentInstructions": false,
"debitParty": {
"personType": "LEGAL_PERSON",
"taxId": "12345678000101",
"bank": "stringst",
"branch": "0001",
"account": "string"
}
}
}
Curl
curl -X POST 'https://sandbox.openfinance.celcoin.dev/baas/v2/automatic/recurrencies/journey1' \
-H "Content-Type: application/json" \
-header 'Authorization: Bearer {{Token}}' \
-d '{
"recurrency": {
"clientRequestId": "a0574329-125f-41bf-9117-fb873421607b",
"interval": {
"start": "2025-07-07",
"end": "2026-07-07",
"frequencyType": "WEEKLY"
},
"recurrencyMinAmount": 200,
"creditParty": {
"branch": "1234",
"account": "1234567",
"taxId": "01234567000189",
"name": "Comércio Digital Ltda."
},
"debitParty": {
"bank": "12345678",
"personType": "LEGAL_PERSON",
"branch": "1234",
"account": "1234567",
"taxId": "01234567000189"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "09876543000121",
"name": "Pague Tudo Serviços S.A."
},
"contract": {
"number": "CONTRATO-2025-ABCD",
"description": "Assinatura mensal de plataforma"
},
"allowsNewAttemptsAfterExpiration": true,
"allowAutoSendingPaymentInstructions": true
}
}'
Response
{
"version": "1.0.0",
"status": 200,
"body": {
"recurrencyId": "RR1393589320250820fqpb80CzMdC",
"clientRequestId": "d82e1931c3e2aa84ec8c8ee16e3320583516c954",
"interval": {
"start": "2025-09-05T00: 00: 00",
"end": null,
"frequencyType": "MONTHLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-06-07T09:45:00-03: 00"
}
],
"amount": null,
"creditParty": {
"bank": "13935893",
"branch": "0001",
"account": "000123456789",
"taxId": "12345678901",
"name": "Jo\u00e3o da Silva"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "61186601000125",
"name": "Jo\u00e3o da Silva"
},
"contract": {
"number": 23,
"description": "Contrato de teste "
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": 80,
"createDate": "2025-06-07T09: 45: 00-03: 00",
"allowAutoSendingPaymentInstructions": true
}
}
Exemplo de webhook disparado quando o pagador recebe a solicitação de recorrência pain.0012
Evento: pix-automatic-recurrency-awaiting-debtor
{
"body": {
"recurrencyId": "RR1393589320250820fqpb80CzMdC",
"clientRequestId": "245395cad398b363a8abb5fc2c79fc628efa220a",
"interval": {
"start": "2025-09-18T00: 00: 00.0000000",
"end": null,
"frequencyType": "MONTHLY"
},
"status": "PENDING_DEBIT_PARTY",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-09-11T00: 00: 00.0000000"
}
],
"amount": 200,
"creditParty": {
"bank": "13935893",
"branch": "0001",
"account": "000123456789",
"taxId": "12345678901",
"name": "Jo\u00e3o da Silva"
},
"debitparty": {
"bank": "10203040",
"personType": "NATURAL_PERSON",
"taxId": "00011122233",
"name": null,
"branch": "10203040",
"account": "98765-4",
"accountType": "CACC",
"stateCode": "3505708"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "47964061070",
"name": "Jo\u00e3o da Silva"
},
"contract": {
"number": "37",
"description": "Contrato de teste "
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"recurrencyMaxAmount": null,
"createDate": "2025-09-11T00: 00: 00.0000000",
"updateDate": "2025-09-11T19: 08: 18.3661312",
"allowAutoSendingPaymentInstructions": false,
"cancellation": null
},
"entity": "pix-automatic-recurrency-awaiting-debtor",
"createTimeStamp": "2025-09-11T19: 08: 18.3662487",
"status": "PENDING_DEBIT_PARTY",
"webhookId": "3dbca47aa0554b15bc3ba10b60e5c33e"
}
Webhook de completed (disparado quando pagador aceita ou recusa a recorrência)
Evento: pix-automatic-recurrency-completed
{
"body": {
"recurrencyId": "RR1393589320250820fqpb80CzMdC",
"clientRequestId": "e5ade67eabf6494f2dc063520a9d81bafdf7d979",
"interval": {
"start": "2025-09-19T00: 00: 00.0000000",
"end": null,
"frequencyType": "MONTHLY"
},
"status": "CONFIRMED",
"journeys": [
{
"status": "ACCEPTED",
"type": 1,
"createDate": "2025-09-12T00: 00: 00.0000000"
}
],
"amount": null,
"creditParty": {
"bank": "13935893",
"branch": "0001",
"account": "000123456789",
"taxId": "12345678901",
"name": "Jo\u00e3o da Silva"
},
"debitparty": {
"bank": "10203040",
"personType": "NATURAL_PERSON",
"taxId": "00011122233",
"name": null,
"branch": "10203040",
"account": "98765-4",
"accountType": "CACC",
"stateCode": "3505708"
},
"debtor": {
"personType": "NATURAL_PERSON",
"taxId": "36057484061",
"name": "Jo\u00e3o da Silva"
},
"contract": {
"number": "102",
"description": "Assinatura carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"recurrencyMaxAmount": null,
"createDate": "2025-09-12T00: 00: 00.0000000",
"updateDate": "2025-09-12T13: 07: 45.0842771",
"allowAutoSendingPaymentInstructions": true,
"cancellation": null
},
"entity": "pix-automatic-recurrency-completed",
"createTimeStamp": "2025-09-12T13: 07: 45.0843698",
"status": "CONFIRMED",
"webhookId": "4c8a48b4518a433a99c0446963ef75de"
}
Tabela de apoio
Para verificar maiores informações, consulte nossa API completa.
Os campos que tiverem (*) são obrigatórios.
| Campo | Descrição | Tipo |
|---|---|---|
| start * | A data de início da recorrência | Date |
| end * | A data fim da recorrência | Date |
| frequencyType * | Weekly = ("WEEKLY") Monthly = ("MONTHLY") Quarter = ("QUARTER") Semester = ("SEMESTER") Yearly = ("YEARLY") | Enum |
| amount | O valor do pagamento para cada ocorrência da recorrência. | Decimal |
| branch * | Agência bancária | String |
| account * | Conta bancária | String |
| name * | O nome completo ou razão social | String |
| taxId * | CNPJ ou CPF | String |
| bank * | ISPB do banco | String |
| personType * | LEGAL_PERSON , PERSONAL_PERSON | String |
| number * | número do contrato | String |
| description | descrição do contrato | String |
| 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) |
Possíveis status de consentimento
| Status | Descrição | Quando é utilizado |
|---|---|---|
| ACCEPTED | A solicitação de adesão do usuário foi aceita. | O cliente aceitou a adesão ao Pix Automático e a instituição confirmou a adesão com sucesso. |
| DENIED | A solicitação de adesão do usuário foi recusada. | O cliente explicitamente recusou participar do Pix Automático durante o fluxo de adesão. |
| PENDING | A solicitação de adesão está aguardando ação do cliente. | A instituição iniciou o processo de adesão, mas o cliente ainda não aceitou nem recusou a solicitação. |
| CANCELLING | A adesão existente está em processo de cancelamento. | O cliente ou a instituição iniciou o cancelamento da adesão, mas ele ainda não foi finalizado. |
| CANCELLED | A adesão foi cancelada com sucesso. | O processo de cancelamento foi concluído e o cliente não está mais vigente para aquele contrato de Pix Automático. |
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) |
Nenhum fluxo de Pix Automático garante ao Recebedor a certeza de recebimento. Em todos os cenários, mesmo que após a adesão, é permitido que o cliente pagador cancele seu consentimento do Pix Automático, que cancele um agendamento ou que o pagamento não seja realizado na data por falta de saldo em conta.
Updated 11 days ago