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": "REC",
"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": "REC",
"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": "REC",
"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": 0,
"location": {
"merchant": {
"postalCode": "12345678",
"city": "Sao Paulo",
"merchantCategoryCode": 5411,
"name": "Loja Exemplo"
}
},
"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": "Servi�os de Assinatura Mensal"
},
"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 '{
"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
{
"status": 100,
"version": "string",
"error": {
"errorCode": "string",
"message": "string"
}
}
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": "a016bc8bd89a4f62be995fa0ebb91d77",
"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
{
"body": {
"recurrencyId": "RR1393589320250820fqpb80CzMdC",
"clientRequestId": "e5ade67eabf6494f2dc063520a9d81bafdf7d979",
"interval": {
"start": "2025-09-19T00: 00: 00.0000000",
"end": null,
"frequencyType": "MONTHLY"
},
"status": "CONFIRMED",
"journeys": [
{
"status": "ACCEPTED",
"type": 2,
"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"
}
Diferença de QR code.
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) |
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 10 days ago