Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Envio de Agendamento

Suggest Edits

O fluxo de envio de agendamento é o mais importante no Pix Automático e é algo que deverá ocorrer em todas as cobranças de um fluxo de Pix Automático.

A empresa recebedora deverá enviar ao cliente pagador, entre 10 dias e 2 dias úteis anterior a data do pagamento a ordem de agendamento para o banco do cliente pagador.

O agendamento pode ser recusado pelo pagador caso esse prazo não seja respeitado ou se a solicitação de agendamento possuir qualquer condição divergente do consentimento inicial realizado pelo cliente pagador.
Para todos os cenários, a Celcoin enviará webhook para o cliente, notificando do aceite ou recusa do pagador.

No início de cada ciclo de recorrência, a Celcoin criará uma instrução de pagamento para ser enviada.

Caso no momento da criação da recorrência tenha sido enviado o parâmetro: allowAutoSendingPaymentInstructions = true

Neste caso, a Celcoin automaticamente enviará a ordem de agendamento ao banco pagador. Este cenário deverá ser utilizado para cobranças recorrentes de valor fixo, onde não é necessário nenhum tipo de ajuste por parte da empresa recebedora a cada novo ciclo de cobrança.


Caso no momento da criação da recorrência tenha sido enviado o parâmetro: allowAutoSendingPaymentInstructions = false

Neste caso, a Celcoin enviará ao recebedor um webhook, informando que o agendamento está pronto para ser criado e a Celcoin aguardará que a empresa recebedora informe as condições de pagamento. Este cenário deverá ser utilizado para cobranças recorrentes de valor variável, onde é necessário que seja informado um valor específico por parte da empresa recebedora a cada novo ciclo de cobrança.

Exemplo de Webhook - "awaiting creditor review"

Evento: pix-automatic-payment-instruction-awaiting-creditor-review
(somente para casos de allowAutoSendingPaymentInstructions = false)

{
  "id": "6bcf6cb3-a91c-4b23-b30a-20c0f5714647",
  "endToEndId": "E36060950202508130000A8LzS0K0z6W",
  "recurrencyId": "RC139358932025060749927585294",
  "amount": 100,
  "expirationDate": "08/11/2025 00:00:00",
  "isWorkingDay": true,
  "nextWorkingDay": null,
  "status": "AWAITING_CREDITOR_EVALUATION",
  "creditParty": {
    "bank": "13935893",
    "branch": "10203040",
    "account": "98765-4",
    "taxId": "19297016000136",
    "name": "Empresa Fictícia"
  },
  "debitParty": {
    "bank": "13935893",
    "personType": "NATURAL_PERSON",
    "taxId": "67167948080",
    "name": "Pessoa Fictícia",
    "branch": "0001",
    "account": "5234565",
    "accountType": null,
    "stateCode": null
  },
  "debtor": {
    "personType": "NATURAL_PERSON",
    "taxId": "67167948080",
    "name": "Pessoa Fictícia"
  },
  "createDate": "2025-07-14T00:00:00.0000000",
  "updateDate": "2025-07-14T19:40:02.5516987",
  "clientRequestId": "00000000-0000-0000-0000-000000000000",
  "cancellation": null,
  "webhookId": "935e6f73343a4974ada18de02fbcea4e"
}

Após o envio deste webhook, a Celcoin ficará aguardando que o recebedor envie as instruções de pagamento. É importante que a empresa respeite os prazos do Pix Automático, e envie as instruções de pagamento dentro da janela permitida(de 10 a 2 dias antes do vencimento), para que a Celcoin tenha tempo de enviar a solicitação ao banco pagador:

Endpoint PUT /recurrencies/{id}/payment-instruction/{id}

Request:

{
 "clientRequestId": "123423432",
 "amount": 100,
 "changeToNextWorkingDay": true
}

Response

{
    "version": "1.0.0",
    "status": 200,
    "body": {
        "id": "asdfgfsdew",
        "endToEndId": "E139358932025060789659528960",
        "recurrencyId": "RR139358932025060758317314721",
        "amount": 100,
        "status": "PENDING_SENDING_DEBTOR",
        "expirationDate": "2025-06-07",
        "nextWorkingDay": null,
        "creditParty": {
            "bank": "13935893",
            "branch": "10203040",
            "account": "98765-4",
            "taxId": "76008951000179",
            "name": "Empresa Fictícia"
        },
        "debtor": {
            "personType": "NATURAL_PERSON",
            "taxId": "00011122233",
            "name": "Pessoa Fictícia"
        },
        "debitParty": {
            "bank": "10203040",
            "personType": "NATURAL_PERSON",
            "taxId": "00011122233",
            "accountType": "CACC",
            "branch": "10203040",
            "account": "98765-4",
            "stateCode": "3505708"
        },
        "createDate": "2025-06-07",
        "clientRequestId": 123423432
    }
}

Após isso, o fluxo ficará na Celcoin pendente de envio ao cliente pagador

Webhook de pending sending debtor (para casos onde allowAutoSendingPaymentInstructions = true) -> o fluxo começa diretamente neste evento:
pix-automatic-payment-instruction-pending-sending-debtor

{
  "id": "asdfgfsdew",
  "endToEndId": "E1393589320250607087449852020",
  "recurrencyId": "RR139358932025060758317314721",
  "amount": 100,
  "expirationDate": "2025-06-07",
  "isWorkingDay": false,
  "nextWorkingDay": null,
  "status": "PENDING_SENDING_DEBTOR",
  "creditParty": {
    "bank": "13935893",
    "branch": "10203040",
    "account": "98765-4",
    "taxId": "76008951000179",
    "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": "NATURAL_PERSON",
    "taxId": "00011122233",
    "name": "Pessoa Fictícia"
  },
  "createDate": "2025-06-07",
  "updateDate": "2025-07-14T19:48:23",
  "clientRequestId": "123423432",
  "cancellation": null,
  "webhookId": "1db615872f2f49c6a09c86760971626e"
}

Após isso, se iniciará de fato o fluxo de agendamento, onde a Celcoin enviará ao pagador a solicitação de agendamento, que poderá ser retornada com um aceite ou recusa do banco pagador.

A recusa do banco pagador poderá ocorrer por diversos motivos, mas não será detalhado o motivo da recusa: a conta do cliente pagador pode ter sido encerrada ou estar bloqueada, por exemplo.

Também é possível que uma recusa ocorra porque a instrução de agendamento foi enviada em valor acima do máximo configurado pelo pagador ou então o agendamento ao pagador foi enviado fora do prazo permitido (por exemplo, somente 1 dia antes do vencimento).

Após enviado a instrução de agendamento pro pagador, ele responderá se foi aceita ou não a instrução de pagamento. Assim que tivermos a resposta, retornaremos para você recebedor o webhook com o status.

Webhook de instrução de pagamento completa, com status de ACCEPTED OU REJECTED pelo pagador.
evento: pix-automatic-payment-instruction-completed

Para este caso, a Celcoin enviará sempre um status de ACCEPTED ou REJECTED.

{
  "id": "asdfgfsdew",
  "endToEndId": "E1393589320250607087449852020",
  "recurrencyId": "RR139358932025060758317314721",
  "amount": 100,
  "expirationDate": "2025-06-07",
  "isWorkingDay": false,
  "nextWorkingDay": null,
  "status": "ACCEPTED| REJECTED",
  "creditParty": {
    "bank": "13935893",
    "branch": "10203040",
    "account": "98765-4",
    "taxId": "76008951000179",
    "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": "NATURAL_PERSON",
    "taxId": "00011122233",
    "name": "Pessoa Fictícia"
  },
  "createDate": "2025-06-07",
  "updateDate": "2025-07-14T19:48:33",
  "clientRequestId": "123423432",
  "cancellation": null,
  "webhookId": "4f829eca69704d4c90686a6d067b1c84"
}

❗️

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