Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Autorização - Jornada 1

Suggest Edits

Envio de notificação para o cliente pagador aderir ao Pix Automático

Caso de uso: A Jornada 1 foi pensada para casos de uso fora do ambiente Pix, como um envio de solicitação de adesão ao cliente pelo WhatsApp, por exemplo.
Caso o cliente em fluxo de WhatsAPP demonstre interesse em aderir a Jornada de Pix Automático, será enviado para ele através da Jornada 1 de Autorização, uma notificação diretamente no seu aplicativo bancário para adesão ao Pix Automático.
Este envio de notificação por parte do cliente recebedor diretamente ao banco do cliente pagador é a jornada 1 de autorização.

Neste fluxo, não há leitura de Qr Code Pix por parte do cliente pagador.

A empresa recebedora enviará os dados para o cliente pagador a partir das suas informações de CPF, Banco, Agência e Conta.

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 1, não existe fluxo de pagamento realizado na hora, somente a adesão para cobranças futuras.


Passos para Integrar

  1. Cliente final solicita a criação de uma recorrência.
  2. Realizar autenticação na API - [API Reference]
  3. Solicita a criação de recorrência da Jornada 1 - [Reference]
  4. Encaminha webhook com a confirmação do recebimento da solicitação.
  5. Encaminha webhook com a resposta da solicitação (Confirmação ou Negação)

Fluxo de integração - Jornada 1 - Autorização da Recorrência


{
    "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
    "recurrency": { //Os campos recurrencyId e recurrency são mutuamente excludentes
        "interval": {
            "start": "2025-07-01T09:00:00Z",
            "end": "2026-07-01T09:00:00Z",
            "frequencyType": "(WEEKLY|MONTHLY|QUARTER|SEMESTER|YEARLY)"
        },
        "amount": 100.75,
        "creditParty": {
            "branch": "0001",
            "account": "123456",
            "bank": "0000000",
            "taxId": "12345678000190",
            "name": "Empresa de Exemplo Ltda."
        },
        "debitParty": {
            "personType": "LEGAL_PERSON",
            "taxId": "98765432000121",
            "bank": "0000000",
            "branch": "0001",
            "account": "123456"
        },
        "debtor": {
            "personType": "NATURAL_PERSON",
            "taxId": "11122233344",
            "name": "João da Silva"
        },
        "contract": {
            "number": "CONTRATO-2025/001",
            "description": "Serviços de consultoria anual"
        },
        "allowsNewAttemptsAfterExpiration": true,
        "maxValueFloor": 200.00,
        "allowAutoSendingPaymentInstructions": false
    }
}

curl --location 'https: //sandbox.openfinance.celcoin.dev/baas/v2/recurrencies/journey1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {
    {Token
    }
}' \
--data '{
    "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
    "recurrency": { //Os campos recurrencyId e recurrency são mutuamente excludentes
        "interval": {
            "start": "2025-07-01T09:00:00Z",
            "end": "2026-07-01T09:00:00Z",
            "frequencyType": "(WEEKLY|MONTHLY|QUARTER|SEMESTER|YEARLY)"
        },
        "amount": 100.75,
        "creditParty": {
            "branch": "0001",
            "account": "123456",
            "bank": "0000000",
            "taxId": "12345678000190",
            "name": "Empresa de Exemplo Ltda."
        },
        "debitParty": {
            "personType": "LEGAL_PERSON",
            "taxId": "98765432000121",
            "bank": "0000000",
            "branch": "0001",
            "account": "123456"
        },
        "debtor": {
            "personType": "NATURAL_PERSON",
            "taxId": "11122233344",
            "name": "João da Silva"
        },
        "contract": {
            "number": "CONTRATO-2025/001",
            "description": "Serviços de consultoria anual"
        },
        "allowsNewAttemptsAfterExpiration": true,
        "maxValueFloor": 200.00,
        "allowAutoSendingPaymentInstructions": false
    }
}'

Exemplo de retorno

👍

Sucesso 200

{
    "status": 200,
    "version": "1.0.0",
    "body": {
        "recurrencyId": "RR1234567820250606093015000",
        "interval": {
            "start": "2025-07-01T10:00:00Z",
            "end": "2026-06-30T10:00:00Z",
            "frequencyType": "(WEEKLY|MONTHLY|QUARTER|SEMESTER|YEARLY)"
        },
        "status": "(CREATED|PROCESSING|PENDING_DEBIT_PARTY|CONFIRMED|CANCELLED|CANCELLATION_REQUEST|CANCELLING)",
        "journeys": [
            {
                "status": "(ACCEPTED|DENIED|PENDING|CANCELLING|CANCELLED)",
                "type": 4,
                "createDate": "2025-06-05T14:30:00Z"
            }
        ],
        "amount": 250.50,
        "creditParty": {
            "branch": "0001",
            "account": "123456",
            "bank": "12345678",
            "taxId": "00000000000100",
            "name": "Recebedor Fictício Ltda.",
            "personType": "NATURAL_PERSON"
        },
        "debitParty": {
            "bank": "12345678",
            "personType": "NATURAL_PERSON",
            "taxId": "99988877766",
            "branch": "0001",
            "account": "78902"
        },
        "debtor": {
            "personType": "LEGAL_PERSON",
            "taxId": "11223344000155",
            "name": "Empresa Paga Tudo S.A."
        },
        "contract": {
            "number": "CONTRATO-ABCD-2025",
            "description": "Contrato de licenciamento de software"
        },
        "allowsNewAttemptsAfterExpiration": false,
        "maxValueFloor": 500.00,
        "createDate": "2025-06-06T09:07:33Z",
        "allowAutoSendingPaymentInstructions": true
    }
}

❗

Error 400

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


Exemplo de webhook disparado quando o pagador recebe a solicitação de recorrência.
Evento: pix-automatic-recurrency-awaiting-debtor

{
    "recurrencyId": "RR9876543220250606180000123",
    "interval": {
        "start": "2025-08-01T08:00:00Z",
        "end": "2026-07-31T08:00:00Z",
        "frequencyType": "MONTHLY"
    },
    "status": "PENDING_DEBIT_PARTY",
    "journeys": [
        {
            "status": "PENDING",
            "type": 4,
            "createDate": "2025-06-06T17:00:00Z"
        }
    ],
    "amount": 500.25,
    "creditParty": {
        "branch": "0001",
        "account": "123456",
        "bank": "12345678",
        "taxId": "00000000000100",
        "name": "Recebedor Fictício Ltda.",
        "personType": "NATURAL_PERSON"
    },
    "debitParty": {
        "bank": "12345678",
        "personType": "NATURAL_PERSON",
        "taxId": "99988877766",
        "branch": "0001",
        "account": "78902"
    },
    "debtor": {
        "personType": "NATURAL_PERSON",
        "taxId": "77766655544",
        "name": "Maria Testadora"
    },
    "contract": {
        "number": "CONTRATO-PJ-XPTO-2025",
        "description": "Contrato de prestação de serviços mensais"
    },
    "allowsNewAttemptsAfterExpiration": true,
    "maxValueFloor": 1000.00,
    "createDate": "2025-06-06T17:55:00Z",
    "allowAutoSendingPaymentInstructions": false
}

Webhook de completed (disparado quando pagador aceita ou recusa a recorrência)

Evento: pix-automatic-recurrency-completed

{
    "recurrencyId": "RR9876543220250606180000123",
    "interval": {
        "start": "2025-08-01T08:00:00Z",
        "end": "2026-07-31T08:00:00Z",
        "frequencyType": "MONTHLY"
    },
    "status": "CONFIRMED",
    "journeys": [
        {
            "status": "ACCEPTED",
            "type": 4,
            "createDate": "2025-06-06T17:00:00Z"
        }
    ],
    "amount": 500.25,
    "creditParty": {
        "branch": "0001",
        "account": "123456",
        "bank": "12345678",
        "taxId": "00000000000100",
        "name": "Recebedor Fictício Ltda.",
        "personType": "NATURAL_PERSON"
    },
    "debitParty": {
        "bank": "12345678",
        "personType": "NATURAL_PERSON",
        "taxId": "99988877766",
        "branch": "0001",
        "account": "78902"
    },
    "debtor": {
        "personType": "NATURAL_PERSON",
        "taxId": "77766655544",
        "name": "Maria Testadora"
    },
    "contract": {
        "number": "CONTRATO-PJ-XPTO-2025",
        "description": "Contrato de prestação de serviços mensais"
    },
    "allowsNewAttemptsAfterExpiration": true,
    "maxValueFloor": 1000.00,
    "createDate": "2025-06-06T17:55:00Z",
    "allowAutoSendingPaymentInstructions": false
}

❗️

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