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": "RR3606095020251106Tgq9f2MpX9r",
  "recurrency": {
    "clientRequestId": "4b2badac-40e7-44be-9f38-ff2dd086a913",
    "amount": 100.99,
    "maxValueFloor": null,
    "interval": {
      "start": "2025-12-01T20:03:58.474Z",
      "end": "2030-04-15T20:03:58.474Z",
      "frequencyType": "WEEKLY"
    },
   "creditParty": {
            "branch": "1234",
            "account": "1234567",
            "taxId": "20745129000136",
            "name": "Comércio Digital Ltda."
        },
    "debitParty": {
      "personType": "LEGAL_PERSON",
      "taxId": "54837139000113",
      "bank": "13935893",
      "account": "3029328",
       "branch":"9898"
    },
    "debtor": {
      "personType": "PERSONAL_PERSON",
      "taxId": "54837139000222",
      "name": "Bento"
    },
    "contract": {
      "number": "2ffdsss00",
      "description": "conta de luz"
    },
    "allowsNewAttemptsAfterExpiration": true,
    "allowAutoSendingPaymentInstructions": true
  }
}

❗️
Caso o campo "debtor" seja os mesmos dados do campo "debitParty", não precisa preencher o "debtor".

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 nossaAPI 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 15 days ago