Envio de Agendamento

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" -> somente para casos de allowAutoSendingPaymentInstructions = false

{
    "entity": "pix-automatic-payment-instruction-awaiting-creditor-review",
    "context": "PIX",
    "cliente": {
        "nome": "",
        "clienteId": 1,
        "localId": 1,
        "usuarioId": 2
    },
    "body":  {
     "endToEndId": string,
     "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
     "amount": decimal,
     "expirationDate": datetime,
     "isWorkingDay": bool,
     "nextWorkingDay": datetime,
     "status": integer (enum PaymentInstructionStatus),
     "creditParty": {
         "ispb": string,
         "taxId": string,
         "personType": string,
         "bank": string | null,
         "account": string,
         "accountType": int,
     },
     "debitParty": {
         "ispb": string,
         "personType": string,
         "taxId": string,
         "personName": string,
         "bank": string | null,
         "account": string,
         "accountType": string,
         "stateCode": string
     },
     "debtor": {
         "personType": string,
         "taxId": string,
         "name": string
     },
  "createDate": datetime,
  "updateDate": datetime,
   "clientRequestId": string | null
 }
}

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, para que a Celcoin tenha tempo de enviar a solicitação ao banco pagador:

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

Request:

{
 "clientRequestId": "string or null",
 "amount": "decimal or null",
 "changeToNextWorkingDay": "boolean or null"
}

Response

{
    "endToEndId": "endToEndId",
    "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
    "amount": decimal,
    "expirationDate": datetime,
    "status": integer (enum PaymentInstructionStatus),
    "creditParty": {
        "ispb": string,
        "taxId": string,
        "personType": string,
        "bank": string | null,
        "account": string,
        "accountType": int,
    },
    "debitParty": {
        "ispb": string,
        "personType": string,
        "taxId": string,
        "personName": string,
        "bank": string | null,
        "account": string,
        "accountType": string,
    },
    "debtor": {
        "personType": string,
        "taxId": string,
        "name": string
    },
 "createDate": datetime,
 "updateDate": datetime,
  "clientRequestId": string | null
}

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)

{
    "entity": "pix-automatic-payment-instruction-pending-sending-debtor",
    "context": "PIX",
    "cliente": {
        "nome": "",
        "clienteId": 1,
        "localId": 1,
        "usuarioId": 2
    },
    "body":  {
     "endToEndId": string,
     "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
     "amount": decimal,
     "expirationDate": datetime,
     "status": integer (enum PaymentInstructionStatus),
     "creditParty": {
         "ispb": string,
         "taxId": string,
         "personType": string,
         "bank": string | null,
         "account": string,
         "accountType": int,
     },
     "debitParty": {
         "ispb": string,
         "personType": string,
         "taxId": string,
         "personName": string,
         "bank": string | null,
         "account": string,
         "accountType": string,
         "stateCode": string
     },
     "debtor": {
         "personType": string,
         "taxId": string,
         "name": string
     },
  "createDate": datetime,
  "updateDate": datetime,
   "clientRequestId": string | null
 }
}

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

Webhook de payment-instruction-completed com aceite ou recusa da instrução de agendamento

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

{
    "entity": "pix-automatic-payment-instruction-completed",
    "context": "PIX",
    "cliente": {
        "nome": "",
        "clienteId": 1,
        "localId": 1,
        "usuarioId": 2
    },
    "body":  {
     "endToEndId": string,
     "recurrencyId": "RRxxxxxxxxyyyyMMddkkkkkkkkkkk",
     "amount": decimal,
     "expirationDate": datetime,
     "status": integer (enum PaymentInstructionStatus),ACCEPTED ou REJECTED
     "creditParty": {
         "ispb": string,
         "taxId": string,
         "personType": string,
         "bank": string | null,
         "account": string,
         "accountType": int,
     },
     "debitParty": {
         "ispb": string,
         "personType": string,
         "taxId": string,
         "personName": string,
         "bank": string | null,
         "account": string,
         "accountType": string,
         "stateCode": string
     },
     "debtor": {
         "personType": string,
         "taxId": string,
         "name": string
     },
  "createDate": datetime,
  "updateDate": datetime,
   "clientRequestId": string | null
 }
}

❗️

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.