Autorização - Jornada 3

Envio de Qr Code para o cliente pagador com pagamento imediato e adesão obrigatória.

Caso de uso: A Jornada 3 foi pensada para casos de uso onde tanto o fluxo de pagamento, quanto a adesão ao Pix Automático para as jornadas futuras, é obrigatório. Um exemplo de uso da Jornada 3 poderia ser um plano de assinatura de serviço de streaming, onde o cliente precisa fazer um primeiro pagamento a vista e obrigatoriamente aderir ao Pix Automático para as próximas cobranças.

Neste fluxo, o cliente recebedor envia um Qr Code Pix Automático para que o cliente pagador realize o pagamento e a adesão ao Pix Automático.

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 3, não existe a opção de não aderir ao Pix Automático. Caso o cliente pagador tente realizar o pagamento e não aderir ao Pix Automático, nem o pagamento imediato será concluído com sucesso.

A Jornada 3 consiste por meio da criação de um QR Code composto com uma location do tipo COBR.
Esse QR Code possui tanto os dados da cobrança imediata quanto da recorrência.

Cenário 1: Criando o location em separado e depois associando esse location a um QR Code.

O aceite é vinculado necessariamente ao pagamento da cobrança imediata. Quando o processo completa disparamos o webhook de completed para o recebedor.

Cenário 1: Criando o location separado e depois associando esse location a um QR Code.

Passos para Integrar

Autenticar na API: Obtenha o token de autenticação. - [API Reference]
Criar o Location: Registre o novo location - [Reference]
Criar e Vincular location a um QR Code do tipo Immediate - [API Reference]
Quando o pagamento for efetuado você receberá 2 webhooks
1. Webhook de Cash in (evento: )
2. Webhook de Confirmação de recorrência (evento: )

Fluxo de integração - Jornada 3 - Autorização da Recorrência - Cenário 1

Cenário 1 - Criando o location em separado e depois associando esse location a um QR Code

JSON de Exemplo

Criar location em separado:
POST /location
Request:

{
 "clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
  "type": "COBR",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": 0,
    "name": "Celcoin"
  }
}

cURL da chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/location' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
 "clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
  "type": "COBR",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": 0,
    "name": "Celcoin"
  }
}'

Exemplo de retorno

👍
Sucesso 200

{
 "locationId": 12345,
  "status": "ACTIVE",
     "clientRequestId": "dc8de35155df4cf6a86c6cf960b797cb",
     "url": "qrcode-h.teste.com.brv1/location/cob/dc8de35155df4cf6a86c6cf960b797cb",
     "emv": "00020101021226930014br.gov.bcb.pix2571qrcode-   h.teste.com.brv1/location/cob/dc8de35155df4cf6a86c6cf960b797cb5204000053039865802BR5907Celcoin6007Barueri623605322b39d30a0dc84ed9bb9d0d79261af1076404D1B6",
  "type": "COBR",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": 0,
    "name": "Celcoin"
  },
 "recurrencyUrl": "qrcode-h.teste.com.brv1/location/cob/dc8de35155df4cf6a86c6cf960b797cb"
}

❗
Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "",
    "message": ""
  }
}

Associar o location tipo COBR a um novo QR Code

JSON de Exemplo
Associar location tipo COBR

POST /collection/immediate

Request:

{
  "key": "[email protected]",
  "debtor": {
    "name": "Fulano de Tal",
    "cpf": "11122233366"
  },
  "amount": {
    "original": 1
  },
  "calendar": {
    "expiration": 8600
  },
  "clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
  "payerQuestion": "Não pagável após vencimento.",
  "locationId": 23212213,

   "recurrency":{
          "clientRequestId":"{{$guid}}",
      "interval":{
         "start":"2025-07-07",

         "frequencyType":"WEEKLY"
      },
      "amount":299.90,
      "creditParty":{
         "branch":"1234",
         "account":"1234567",
         "taxId":"01234567000189",
         "name":"Comércio Digital Ltda."
      },
    
      "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 --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/immediate' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
 "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "payerQuestion": "Não pagável após vencimento.",
  "key": "ab7e4702-fb05-4809-94c9-a7bfbe9aece3",
  "locationId": 775645,
  "debtor": {
    "name": "Fulano de Tal",
    "cpf": "11122233366",
    "cnpj": "1112223300100"
  },
  "amount": {
    "original": 0,
    "changeType": 0,
    "withdrawal": {
      "vldnAmount": 10,
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    },
    "change": {
      "vldnAmount": 10,
      "vlcpAmount": 15.55,
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    }
  },
  "calendar": {
    "expiration": 86400
  },
  "additionalInformation": [
    {
      "value": "Assinatura de serviço",
      "key": "Produto 1"
    }
  ],
"recurrency: {
 // Se recurrencyId for informado, os demais não podem estar presentes
     "recurrencyId": "id da recorrência, seguindo o formato: RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
        "interval": {
            "start": "datetime",
            "end": "datetime",
            "frequencyType": "integer (enum FrequencyType)"
        },
        "amount": "decimal | null",
        "creditParty": {
            "bank": "string",
            "taxId": "string",
            "name": "string"
        },
      "debitParty": {
   "ispb": string,
   "personType": string,
   "taxId": string,
   "bank": string | null,
   "account": string,
   "stateCode": string
  },
  "debtor": {
   "personType": string,
   "taxId": string,
   "name": string
  },
        "contract": {
            "number": "string",
            "description": "string | null"
        },
  "allowsNewAttemptsAfterExpiration": boolean
  "maxValueFloor": decimal | null,
  "allowAutoSendingPaymentInstructions": bool
 }
}'

Exemplo de retorno

👍
Sucesso 200

{
    "revision": 0,
    "transactionId": 4000278856,
    "clientRequestId": "ada22f39-e08e-4d0a-8d28-e60712d58a40",
    "status": "ACTIVE",
    "lastUpdate": null,
    "payerQuestion": "Não pagável após vencimento.",
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": "11122233366",
        "cnpj": null
    },
    "amount": {
        "original": 1,
        "changeType": 0,
        "withdrawal": null,
        "change": null
    },
    "location": {
        "merchant": {
            "postalCode": "06416230",
            "city": "barueri",
            "merchantCategoryCode": 5651,
            "name": "Teste testando"
        },
        "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/2be72fb3d9334070b91c48452a9ef1",
        "emv": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/pixqrcode/v2/2be72fb3d9334070b91c48452a9ef15204000053039865802BR5914Teste testando6007barueri62070503***6304614C",
        "type": "COB",
        "locationId": "4000928432",
        "id": "6867a36a03213cd507d1ac0a"
    },
    "key": "[email protected]",
    "calendar": {
        "expiration": 8600
    },
    "createAt": "2025-07-04T09:48:26.9104112+00:00",
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000278856",
    "recurrency": {
        "recurrencyId": "RR139358932025060747690230748",
        "clientRequestId": "4e867ad5-0cea-408f-b4cc-b93f527c642a",
        "interval": {
            "start": "2025-07-07T00:00:00",
            "end": null,
            "frequencyType": "WEEKLY"
        },
        "status": "CREATED",
        "journeys": [
            {
                "status": "PENDING",
                "type": 3,
                "createDate": "2025-06-07T09:45:00-03:00"
            }
        ],
        "amount": 299.9,
        "creditParty": {
            "bank": "13935893",
            "branch": "1234",
            "account": "1234567",
            "taxId": "01234567000189",
            "name": "Comércio Digital Ltda."
        },
        "debtor": {
            "personType": "LEGAL_PERSON",
            "taxId": "09876543000121",
            "name": "Pague Tudo Serviços S.A."
        },
        "contract": {
            "number": "CONTRATO-2025-ABCD",
            "description": "null"
        },
        "allowsNewAttemptsAfterExpiration": true,
      "recurrencyMinAmount": null,
        "createDate": "2025-06-07T09:45:00-03:00",
        "allowAutoSendingPaymentInstructions": true
    }
}

❗
Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "",
    "message": ""
  }
}

Webhook

Após o pagador realizar o pagamento do pix imediato que siginifica a autorização da recorrências para as próximas cobranças serem via pix automático, será recebido um webhook de pix cash in convencional de evento "pix-payment-in" e depois o do aceite da recorrência (evento abaixo).

Webhook de completed (disparado quando pagador aceita 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": 3,
                "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"
}

🚧
Importante
Para estes casos da Jornada 3, a Celcoin sempre retornará o status de CONFIRMED, dado que a adesão é obrigatória. Caso o cliente não realize a adesão, nem o pagamento será recebido e o QR Code seguirá o fluxo normal de expiração de um Qr Code Pix.

❗️
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.

Diferença de QR code.

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)

Updated 15 days ago