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

Autorização - Jornada 4

Envio de Qr Code para o cliente pagador com pagamento imediato e adesão opcional.


Caso de uso: A Jornada 4 foi pensada para casos de uso onde o fluxo de pagamento é obrigatório, porém a adesão ao Pix Automático é opcional.

Um exemplo de uso da Jornada 4 é um caso de pagamento de fatura de luz ou água, onde o cliente pagador realizará o pagamento do serviço daquele mês, mas pode não desejar aderir ao Pix Automático para os próximos meses.

Neste fluxo, o cliente recebedor envia um Qr Code Pix Automático para que o cliente pagador realize o pagamento e, se desejar, 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 4, o pagamento é obrigatório, mas a adesão é opcional.


A Jornada 4 ocorre por meio da criação de um QR Code composto com uma location do tipo COBVR. Esse QR Code possui tanto os dados da cobrança com vencimento quanto da recorrência.

  • Criando o location em separado e depois associando esse location a um QR Code.

O aceite é nesse caso é opcional, após efetivar o pagamento a instituição recebedora pergunta se o cliente deseja aceitar a recorrência. Quando o processo seja aceito disparamos o webhook de completed para o recebedor, se o cliente não aceitar não enviamos nenhum webhook.


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 - [API Reference]
  3. Criar e Vincular location a um QR Code do tipo Duedate- [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: ) (caso a recorrência seja aceita)

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





Solicita a criação do location

JSON de Exemplo

POST /location
Request:

{
 "clientRequestId": "a016bc8bd89a4f62be995fa0ebb91d77",
  "type": "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": "COBVR",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": 0,
    "name": "Celcoin"
  }
}'

Perceba que o campo type, deve ser preenchido com o valor COBVR (cobrança com vencimento recorrente), para indicar que é de um tipo pix automático.

Exemplo de retorno

👍

Sucesso 200

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

Error 400

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


Associar o location tipo COBVR a um novo QR Code

JSON de Exemplo

Neste momento são informados os dados da recorrência do pix automático, como a frequência, os campos allowsNewAttemptsAfterExpiration que é se terá ou não retentativas após o vencimento e allowAutoSendingPaymentInstructions se é cobrança de valor variável ou não. Caso seja de valor variável, deverá preencher o campo como = false e o recebedor terá que todo mês enviar qual será o valor.
Se for valor fixo = true, a própria Celcoin iniciará o fluxo de cobrança e só enviará o webhook informando se foi aceita ou não.

POST /collection/duedate

Request:

{
    "clientRequestId": "e978fafe-1374-4e34-b419-f5b0f459e85f",
    "expirationAfterPayment": 10,
    "duedate": "2025-07-07",
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": "11122233366",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "postalCode": "01202003",
        "email": "[email protected]"
    },
    "receiver": {
        "name": "João da Silva",
        "cpf": "11122233366",
        "postalCode": "01202003",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP"
    },
    "locationId": 234545,
    "amount": 5.55,
    "key": "5d000ece-b3f0-47b3-8bdd-c183e8875862",
   "recurrency":{
          "clientRequestId":"2005630c-cd0a-4467-9b3f-adc473fb7ea0",
      "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/duedate' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
 "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "expirationAfterPayment": 10,
  "duedate": "2021-04-29 00:00:00",
  "debtor": {
    "name": "Fulano de Tal",
    "cpf": "11122233366",
    "cnpj": "1112223300100",
    "city": "Barueri",
    "publicArea": "Avenida Brasil",
    "state": "SP",
    "postalCode": "01202003",
    "email": "[email protected]"
  },
  "receiver": {
    "name": "João da Silva",
    "cpf": "11122233366",
    "cnpj": "1112223300100",
    "postalCode": "01202003",
    "city": "Barueri",
    "publicArea": "Avenida Brasil",
    "state": "SP",
    "fantasyName": "Nome de Comercial"
  },
  "locationId": 55845,
  "amount": 15.63,
  "amountDiscount": {
    "discountDateFixed": [
      {
        "date": "2021-04-29",
        "amountPerc": "1.00"
      }
    ],
    "hasDiscount": false,
    "hasDicount": true,
    "modality": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED",
    "amountPerc": "0.00"
  },
  "amountDicount": {
    "discountDateFixed": [
      {
        "date": "2021-04-29",
        "amountPerc": "1.00"
      }
    ],
    "hasDiscount": false,
    "hasDicount": true,
    "modality": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED",
    "amountPerc": "0.00"
  },
  "amountAbatement": {
    "hasAbatement": false,
    "amountPerc": "0.00",
    "modality": "FIXED_VALUE"
  },
  "amountFine": {
    "hasFine": false,
    "amountPerc": "0.00",
    "modality": "FIXED_VALUE"
  },
  "amountInterest": {
    "hasInterest": false,
    "amountPerc": "0.00",
    "modality": "VALUE_CALENDAR_DAYS"
  },
  "additionalInformation": [
    {
      "value": "Assinatura de serviço",
      "key": "Produto 1"
    }
  ],
  "payerQuestion": "pagamento referente a...",
  "key": "5d000ece-b3f0-47b3-8bdd-c183e8875862",
"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

{
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000278871",
    "transactionId": 4000278871,
    "clientRequestId": "54805e92-37fc-4936-b5cd-2ecfdc6f56f3",
    "status": "ACTIVE",
    "lastUpdate": null,
    "payerQuestion": null,
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": "11122233366",
        "cnpj": null,
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "postalCode": "01202003",
        "email": "[email protected]"
    },
    "amount": {
        "original": 5.55,
        "discount": null,
        "abatement": null,
        "fine": null,
        "interest": null
    },
    "location": {
        "merchant": {
            "postalCode": "06416230",
            "city": "barueri",
            "merchantCategoryCode": "5651",
            "name": "Teste testando"
        },
        "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cobv/2dcb1bc1b1807edf3a112eac643954",
        "emv": "00020101021226980014br.gov.bcb.pix2576qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cobv/2dcb1bc1b1807edf3a112eac6439545204000053039865802BR5914Teste testando6007barueri62070503***63040354",
        "type": "COBV",
        "locationId": "4000928439",
        "id": "4000928439"
    },
    "key": "[email protected]",
    "receiver": {
        "name": "Joao da Silva",
        "cpf": "11122233366",
        "cnpj": null,
        "postalCode": "01202003",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "fantasyName": null
    },
    "calendar": {
        "expirationAfterPayment": "10",
        "createdAt": "2025-07-04T10:56:49.52229Z",
        "dueDate": "2025-07-07T00:00:00Z"
    },
    "createAt": "2025-07-04T10:56:49.52229Z",
    "recurrency": {
        "recurrencyId": "RR139358932025060794206870902",
        "clientRequestId": "f7819ce5-6ed0-4972-a3a9-492ce1d435e4",
        "interval": {
            "start": "2025-07-07T00:00:00",
            "end": null,
            "frequencyType": "WEEKLY"
        },
        "status": "CREATED",
        "journeys": [
            {
                "status": "PENDING",
                "type": 4,
                "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,
        "recurrencyMaxAmount": 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


{
    "body": {
        "recurrencyId": "RR1393589320250820fqpb80CzMdC",
        "clientRequestId": "e5ade67eabf6494f2dc063520a9d81bafdf7d979",
        "interval": {
            "start": "2025-09-19T00: 00: 00.0000000",
            "end": null,
            "frequencyType": "MONTHLY"
        },
        "status": "CONFIRMED",
        "journeys": [
            {
                "status": "ACCEPTED",
                "type": 4,
                "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"
}
❗️

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


Possíveis status de consentimento

StatusDescriçãoQuando é utilizado
ACCEPTEDA 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.
DENIEDA 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.
PENDINGA 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.
CANCELLINGA 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.
CANCELLEDA 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 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 15 days ago