Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com
Start typing to search…

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. Existem duas formas de criar esse location::

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

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

  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 location a um QR Code do tipo Immediate - [API Reference]
  4. 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

  1. 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

POST /collection/immediate

Request:

{
  "key": "[email protected]",
  "debtor": {
    "name": "Fulano de Tal",
    "cpf": "11122233366"
  },
  "amount": {
    "original": 1
  },
  "calendar": {
    "expiration": 8600
  },
  "clientRequestId": "{{$guid}}",
  "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": ""
  }
}

Cenário 2 - Criar o QR Code e associar a recorrencia existente

Passos para Integrar

  1. Autenticar na API: Obtenha o token de autenticação. - [API Reference]
  2. Realiza a criação de um Location + QR Code Simultaneamente - [API Reference]
  3. 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 2



Criar o QR Code e associar a recorrencia existente

JSON de Exemplo

POST /collection/immediate

Request:

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

 "recurrencyId":"RR13935893202506071234567890c"
}

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 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": 3,
      "createDate": "2025-07-14T00:00:00.0000000"
    }

  ],
  "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"
}
🚧

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.


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)


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


CampoDescriçãoTipo
taxId*CNPJ do Recebedorstring
name*Nome do recebedorstring
bank*ISPB do banco recebedorstring

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


CampoDescriçãoTipo
number*Número do contrato vinculado.string
descriptiondescrição do contratostring

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 6 days ago