Autorização - Jornada 2
A Jornada 2 consiste na geração de um QR Code de recorrência vinculado a uma location do tipo 'REC'. Há duas formas de criar essa location:
- Cenário 1: Criação Independente: Configure a location primeiro e, em seguida, associe-a a um QR Code existente.
- Cenário 2 :Criação Simultânea: Gere o QR Code e sua respectiva location ao mesmo tempo.
Uma vez que o QR Code é criado e enviado ao pagador, ele fará a leitura e poderá aceitar ou recusar a transação. Assim que o pagador tomar sua decisão (aceite ou recusa), o webhook 'completed' é automaticamente enviado ao recebedor.
Para adesões de Pix Automático através da Jornada 2, não existe fluxo de pagamento realizado na hora, somente a adesão para cobranças futuras.
Cenário 1: Criação e associação de um 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 a Jornada 2: Associe a jornada 2 ao location recém-criado - [API Reference]
- Receber Webhook de Resposta: Aguarde o webhook com a confirmação ou negação da solicitação.
Fluxo de integração - Jornada 2 - Autorização da Recorrência - Cenário 1
Solicita a criação do location
JSON de Exemplo
POST /location
Request:
{
"clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
"type": "COB" | "COBV" | "REC" | "COBR" | "COBVR",
"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": "COB" | "COBV" | "REC" | "COBR" | "COBVR",
"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": "COB" | "COBV" | "REC" | "COBR" | "COBVR",
"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 REC a um novo QR Code de recorrência
JSON de Exemplo
POST /recurrencies/journey2
Request:
{
"locationId": 12345,
"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/baas/v2/recurrencies/journey2' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"locationId":1234567890123456789,
"recurrencyId":" RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
"recurrency":{
"interval":{
"start":"2025-07-07T13:00:00-03:00",
"end":"2026-07-07T13:00:00-03:00",
"frequencyType":1
},
"amount":299.90,
"creditParty":{
"bank":"Banco ABC S.A.",
"taxId":"01234567000189",
"name":"Comércio Digital Ltda."
},
"debitParty":{
"ispb":"12345678",
"personType":"NATURAL_PERSON",
"taxId":"98765432100",
"bank":"Banco Exemplo Online",
"account":"11223-4",
"stateCode":"PR"
},
"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,
"maxValueFloor":40.00,
"allowAutoSendingPaymentInstructions":false
}
}'
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": 200,
"body": {
"recurrencyId": "RR139358932025060792986900072",
"clientRequestId": "ed6664e7-d2eb-4e5c-8f7d-072a9619a9ec",
"interval": {
"start": "2025-07-07T00:00:00",
"end": null,
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 2,
"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": "Contrato de venda de carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMaxAmount": null,
"createDate": "2025-06-07T09:45:00-03:00",
"allowAutoSendingPaymentInstructions": true,
"location": {
"merchant": {
"postalCode": "06454000",
"city": "Barueri",
"merchantCategoryCode": 5411,
"name": "Mercado Fictício"
},
"url": null,
"recurrencyUrl": "https://qrcode-h.pix.celcoin.com.br/v2/rec/a56njW4MKT6l5",
"emv": "00020101021226360014BR.GOV.BCB.PIX8025https://qrcode-h.pix.celcoin.com.br/v2/rec/uBvD486kdkgzj9sa0Ue53039865802BR5907Empresa6008SaoPaulo62100506Rec016304C7EC",
"type": "REC",
"locationId": 2133443,
"id": 2133443
}
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "",
"message": ""
}
}
Cenário 2 - Criar o QR Code e o location simultaneamente.
Passos para Integrar
- Autenticar na API: Obtenha o token de autenticação. - [API Reference]
- Criando a Jornada 2: Local e QR Code Simultaneamente - [API Reference]
- Receber Webhook de Resposta: Aguarde o webhook com a confirmação ou negação da solicitação.
Fluxo de integração - Jornada 2 - Autorização da Recorrência - Cenário 2
Solicita a criação da jornada 2 e o location simultaneamente
JSON de Exemplo
Criar QR Code e location
POST /recurrencies/journey2
Request:
{
"location": {
"clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
"merchant": {
"postalCode": "01201005",
"city": "Barueri",
"merchantCategoryCode": 0000,
"name": "Celcoin"
}
},
"recurrency": {
"clientRequestId": "{{$guid}}",
"interval": {
"start": "2025-07-07",
"frequencyType": "WEEKLY"
},
"amount": 299.90,
"creditParty": {
"bank": "12345678",
"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": false
}
}
cURL da chamada
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v2/recurrencies/journey2' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"location": {
"clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
"merchant": {
"postalCode": "01201005",
"city": "Barueri",
"merchantCategoryCode": 0,
"name": "Celcoin"
}
},
// Os campos recurrencyId e recurrency são mutuamente excludentes
"recurrencyId":" RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
"recurrency":{
"interval":{
"start":"2025-07-07T13:00:00-03:00",
"end":"2026-07-07T13:00:00-03:00",
"frequencyType":1
},
"amount":299.90,
"creditParty":{
"bank":"Banco ABC S.A.",
"taxId":"01234567000189",
"name":"Comércio Digital Ltda."
},
"debitParty":{
"ispb":"12345678",
"personType":"NATURAL_PERSON",
"taxId":"98765432100",
"bank":"Banco Exemplo Online",
"account":"11223-4",
"stateCode":"PR"
},
"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,
"maxValueFloor":40.00,
"allowAutoSendingPaymentInstructions":false
}
}'
Exemplo de retorno
Sucesso 200
{
"version": "1.0.0",
"status": 200,
"body": {
"recurrencyId": "RR139358932025060792986900072",
"clientRequestId": "ed6664e7-d2eb-4e5c-8f7d-072a9619a9ec",
"interval": {
"start": "2025-07-07T00:00:00",
"end": null,
"frequencyType": "WEEKLY"
},
"status": "CREATED",
"journeys": [
{
"status": "PENDING",
"type": 2,
"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": "Contrato de venda de carro"
},
"allowsNewAttemptsAfterExpiration": true,
"recurrencyMinAmount": null,
"createDate": "2025-06-07T09:45:00-03:00",
"allowAutoSendingPaymentInstructions": true,
"location": {
"merchant": {
"postalCode": "06454000",
"city": "Barueri",
"merchantCategoryCode": 5411,
"name": "Mercado Fictício"
},
"url": null,
"recurrencyUrl": "https://qrcode-h.pix.celcoin.com.br/v2/rec/a56njW4MKT6l5",
"emv": "00020101021226360014BR.GOV.BCB.PIX8025https://qrcode-h.pix.celcoin.com.br/v2/rec/uBvD486kdkgzj9sa0Ue53039865802BR5907Empresa6008SaoPaulo62100506Rec016304C7EC",
"type": "REC",
"locationId": 2133443,
"id": 2133443
}
}
}
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "",
"message": ""
}
}
Webhook de completed
Esse webhook será recebido quando o pagador aceita a recorrência gerada via o QR code que você criou.
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": "PENDING",
"type": 1,
"createDate": "2025-07-14T00:00:00.0000000"
},
{
"status": "ACCEPTED",
"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,
"recurrencyMaxAmount": null,
"recurrencyMinAmount": null,
"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 about 21 hours ago