Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Autorização - Jornada 2

Suggest Edits

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


  1. Autenticar na API: Obtenha o token de autenticação. - [API Reference]
  2. Criar o Location: Registre o novo location - [Reference]
  3. Criar e Vincular a Jornada 2: Associe a jornada 2 ao location recém-criado - [API Reference]
  4. 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

  1. Autenticar na API: Obtenha o token de autenticação. - [API Reference]
  2. Criando a Jornada 2: Local e QR Code Simultaneamente - [API Reference]
  3. 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.


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.

Updated about 22 hours ago