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

  1. Cliente final solicita a criação de uma recorrência.
  2. Realizar autenticação na API - [API Reference]
  3. Solicita a criação de recorrência da Jornada 1 - [Reference]
  4. Encaminha webhook com a confirmação do recebimento da solicitação.
  5. 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.


CampoDescriçãoTipo
start *A data de início da recorrênciaDate
end *A data fim da recorrênciaDate
frequencyType *Weekly = ("WEEKLY")
Monthly = ("MONTHLY")
Quarter = ("QUARTER")
Semester = ("SEMESTER")
Yearly = ("YEARLY")
Enum
amountO valor do pagamento para cada ocorrência da recorrência.Decimal
branch *Agência bancáriaString
account *Conta bancáriaString
name *O nome completo ou razão socialString
taxId *CNPJ ou CPFString
bank * ISPB do bancoString
personType *LEGAL_PERSON , PERSONAL_PERSONString
number *número do contratoString
descriptiondescrição do contratoString
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)



❗️

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.