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
{
"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
}
}
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
{
"version": "1.0.0",
"status": 200,
"body": {
"recurrencyId": "RR1393589320250607279843857613",
"clientRequestId": "51ca63b2-f711-4873-856a-06c06ff6b06c",
"interval": {
"start": "2025-07-07T00:00:00",
"end": null,
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-06-07T09:45:00-03:00"
}
],
"amount": 200,
"creditParty": {
"bank": "13935893",
"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": "null"
},
"allowsNewAttemptsAfterExpiration": true,
"":null,
"createDate": "2025-06-07T09:45:00-03:00",
"allowAutoSendingPaymentInstructions": true
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "",
"message": ""
}
}
Criação de recorrência com valor variável
JSON de Exemplo: Método: POST /recurrencies/journey1
body
{
"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
}
}
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": "RR1393589320250607279843857613",
"clientRequestId": "51ca63b2-f711-4873-856a-06c06ff6b06c",
"interval": {
"start": "2025-07-07T00:00:00",
"end": null,
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-06-07T09:45:00-03:00"
}
],
"amount": null,
"creditParty": {
"bank": "13935893",
"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": "null"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount":20,
"createDate": "2025-06-07T09:45:00-03:00",
"allowAutoSendingPaymentInstructions": true
}
}
Associar a uma recorrencia já existente
Método: POST /recurrencies/journey1
Body
{
"recurrencyId":"RR13935893202506071234567890b"
}
Response
{
"version": "1.0.0",
"status": 200,
"body": {
"recurrencyId": "RR13935893202506071234567890b",
"clientRequestId": "idasasdddas-dasdasdasd-dadadasdas-ddasdasdassd",
"interval": {
"start": "2025-06-07T09:45:00-03:00",
"end": "2025-06-07T09:45:00-03:00",
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-06-07T09:45:00-03:00"
},
{
"status": "PENDING",
"type": 2,
"createDate": "2025-06-07T09:45:00-03:00"
}
],
"amount": 100,
"creditParty": {
"bank": "13935893",
"taxId": "01483378000156",
"branch": "0001 ",
"account": "1234556",
"name": "Empresa Fictícia"
},
"debitParty": {
"bank": "10203040",
"personType": "NATURAL_PERSON",
"taxId": "00011122233",
"branch": "10203040",
"account": "98765-4"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "14843862000190",
"name": "Empresa Fictícia 1"
},
"contract": {
"number": "Contrato-12345",
"description": "Assinatura carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"createDate": "2025-06-07T09:45:00-03:00",
"allowAutoSendingPaymentInstructions": false
}
}
Exemplo de webhook disparado quando o pagador recebe a solicitação de recorrência pain.0012
Evento: pix-automatic-recurrency-awaiting-debtor
{
"recurrencyId": "RR13935893202506071234567890b",
"clientRequestId": "idasasdddas-dasdasdasd-dadadasdas-ddasdasdassd",
"interval": {
"start": "2025-07-21",
"end": "2025-06-07",
"frequencyType": "WEEKLY"
},
"status": "PENDING_DEBIT_PARTY",
"journeys": [
{
"status": "PENDING",
"type": 1,
"createDate": "2025-07-14T00:00:00.0000000"
},
{
"status": "PENDING",
"type": 2,
"createDate": "2025-06-07"
}
],
"amount": 100,
"creditParty": {
"bank": "13935893",
"branch": "0001 ",
"account": "1234556",
"taxId": "01483378000156",
"name": "Empresa Fictícia"
},
"debitparty": {
"bank": "10203040",
"personType": "NATURAL_PERSON",
"taxId": "00011122233",
"branch": "10203040",
"account": "98765-4",
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "14843862000190",
"name": "Empresa Fictícia 1"
},
"contract": {
"number": "Contrato-12345",
"description": "Assinatura carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"recurrencyMaxAmount":100,
"createDate": "2025-07-14T00:00:00.0000000",
"updateDate": "2025-07-14T19:08:17.9793507",
"allowAutoSendingPaymentInstructions": false,
"cancellation": null,
"webhookId": "9b647bfc3b0e42aeab995f79aa340939"
}
Webhook de completed (disparado quando pagador aceita ou recusa a recorrência)
Evento: pix-automatic-recurrency-completed
{
"recurrencyId": "RR13935893202506071234567890b",
"clientRequestId": "idasasdddas-dasdasdasd-dadadasdas-ddasdasdassd",
"interval": {
"start": "2025-07-21T00:00:00.0000000",
"end": "2025-06-07",
"frequencyType": "WEEKLY"
},
"status": "CONFIRMED",
"journeys": [
{
"status": "ACCEPTED",
"type": 1,
"createDate": "2025-07-14T00:00:00.0000000"
},
{
"status": "PENDING",
"type": 2,
"createDate": "2025-06-07"
}
],
"amount": 100,
"creditParty": {
"bank": "13935893",
"branch": "0001 ",
"account": "1234556",
"taxId": "01483378000156",
"name": "Empresa Fictícia"
},
"debitparty": {
"bank": "10203040",
"personType": "NATURAL_PERSON",
"taxId": "00011122233",
"name": null,
"branch": "10203040",
"account": "98765-4",
"accountType": "CACC",
"stateCode": "3505708"
},
"debtor": {
"personType": "LEGAL_PERSON",
"taxId": "14843862000190",
"name": "Empresa Fictícia 1"
},
"contract": {
"number": "Contrato-12345",
"description": "Assinatura carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"recurrencyMaxAmount":100,
"createDate": "2025-07-14T00:00:00.0000000",
"updateDate": "2025-07-14T19:08:17.9793507",
"allowAutoSendingPaymentInstructions": false,
"cancellation": null,
"webhookId": "8e6cf4529e714ee696c1360d026dc7c2"
}
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) |
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.
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 21 days ago