O Débito Direto Autorizado, conhecido como DDA, é uma ferramenta desenvolvida pela Febraban e está em uso desde 2009, facilitando o pagamento de contas e auxiliando no planejamento financeiro.

O DDA permite acesso de forma eletrônica aos boletos emitidos em um determinado CPF ou CNPJ, tirando a necessidade de tê-los em papel. É importante ressaltar que o DDA é apenas a visualização eletrônica da cobrança, ou seja, o usuário continua decidindo como e quando realizar o pagamento. Deixar de efetuar o pagamento via internet banking, incide nas mesmas regras que o não pagamento da via física.

Nesse artigo você irá aprender sobre:

• Vantagens do DDA
• Diferença de DA e DDA
• Tipos de cobrança que o DDA retorna
• Configurar webhooks
• Cadastrar e excluir usuário do DDA
• Notificações de boletos

Pré requisitos para implementação:

• Possuir uma chave única da API da Celcoin, para isso é necessário solicitar ao suporte a criação de um usuário. Entre em contato com o suporte aqui.
• Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.
• Ter o produto/solução contratada, caso queira usar a funcionalidade, por favor, entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Vantagens do DDA

Com o DDA é possível finalizar o pagamento do boleto direto no internet banking e isso reduz riscos de erro na digitação do código de barras na hora de pagar. Além disso, o usuário possui um maior controle das suas finanças, uma vez que consegue mapear todas as contas emitidas em seu CPF/CNPJ.

Para as Fintechs, o DDA permite obter novos débitos e todas as informações necessárias para liquidação dos boletos em canais digitais. Além de centralizar a gestão dos débitos e melhorar a visibilidade do histórico de eventuais despesas periódicas por CPF e CNPJ.

Diferença de DDA e DA

No Débito Automático (DA), é necessário cadastrar a cobrança usando o código identificador da fatura uma única vez. Após isso, na data de vencimento do débito será executado o pagamento automaticamente retirando o saldo da conta. O DA está ligado a cobranças recorrentes provenientes de convênios como: Vivo, Tim, Cemig, Sabesp, Enel e etc.

No Débito direto autorizado (DDA), é possível consultar as contas a pagar e até ser notificado dos boletos em aberto, mas é necessário ação do usuário autorizando o pagamento. Ou seja, o pagamento não é executado de forma automática. Além disso, as cobranças relacionadas ao DDA são boletos bancários registrados por instituições financeiras gerados através da CIP, como mensalidades de escola, por exemplo.

Tipos de cobranças retornadas no DDA

Todos os boletos de cobrança registrados por instituições bancárias, incluindo aluguel, plano de saúde, condomínio, mensalidade de escolas, clubes, faturas de cartão, compras realizadas em boleto e etc.

Tipos de cobranças que não retornam no DDA

Cobranças não bancárias tais como contas de consumo (água, luz e etc) e tributos (IPVA, IPTU).

Caso de uso

Como Fintech quero notificar os meus usuários sobre todos os boletos em aberto que eles possuem para que possam efetuar o pagamento no meu aplicativo.

Com objetivo de exibir como pode ser habilitado o DDA e a apresentação de boletos para um usuário, criamos essa apresentação que simula o processo como todo:

Como funciona o DDA

Para habilitar o DDA para o usuário é necessário criar a subscrição do seu CPF ou CNPJ. Nesse cadastro deve ser solicitado o aceite do usuário no termo de adesão, conforme disposto nesse link. Isso significa que, além do aceite do usuário para registrar-se no DDA, é preciso coletar o nome, documento (CPF ou CNPJ), endereço, email e telefone.

❗

Atenção!

A coleta dos dados e aceite do usuário no termo de adesão do DDA é obrigatória. O documento deve ser armazenado pela Fintech e ele poderá ser solicitado pela Celcoin por auditoria interna ou por solicitação do Bacen.

O DDA funciona de forma assíncrona, isso significa que a requisição é feita, mas o retorno é enviado através de notificações de webhooks depois de serem processados. Então há envio de notificação sobre o cadastro e exclusão da subscrição e notificação sobre os boletos.

É importante salientar que o cadastro e exclusão funcionam apenas em dias úteis e numa janela de 6h até às 22h. Quando solicitado em dia não útil, o registro ou exclusão será programado para o próximo dia útil.

Veja como configurar webhooks:

Configurar webhooks

Para configurar o recebimento das notificações do DDA, é necessário realizar um POST na API Configurar webhooks informando a URL que receberá os webhooks, quais eventos deseja receber e autenticação (se houver).

Lista de eventos:

Subscription: todas as notificações referentes ao cadastro do usuário no DDA.
Deletion: todas as notificações referentes a exclusão do usuário no DDA.
Invoice: todas as notificações referentes aos boletos dos usuários.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/dda-servicewebhook-webservice/v1/webhook/register' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "typeEventWebhook": "Invoice",
    "url": "https://webhook.site/d24aa98f-1837-4698-8825-688f94390cfe",
    "basicAuthentication": {
        "identification": "João",
        "password": "Um@Pro7ec@o"
    }
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "typeEventWebhook": "Invoice",
        "url": "https://webhook.site/d24aa98f-1837-4698-8825-688f94390cfe",
        "basicAuthentication": {
            "identification": "João",
            "password": "Um@Pro7ec@o"
        },
        "oAuthTwo": null
    }
}

O campo typeEventWebhook define qual evento está sendo configurado na requisição, conforme descrito na lista de eventos, e o campo url define para qual endereço será enviado as notificações daquele evento. É possível configurar uma url diferente para cada evento. A requisição configura um evento por vez, ou seja, é necessário realizar 3 solicitações para configurar todos os eventos de notificações (mesmo que utilize a mesma url).

Além disso, é possível configurar a permissão de acesso a sua URL por dois métodos: basicAuthentication ou oAuthTwo. A configuração basicAuthentication solicita a identification que funciona como o login e a password que é a senha. Os dois campos são obrigatórios, caso selecione esse tipo de autenticação.

Exemplo apenas do trecho de autenticação basicAuthentication:

Exemplo: 
  "basicAuthentication": {
    "identification": "João",
    "password": "Um@Pro7ec@o"
  }'

Para configurar oAuthTwo, que funciona como uma autenticação de token de acesso, é necessário informar:

• endpoint: que é a URL para autenticação. Ex: https://yoursite.net/oauth
• grantType: tipo de concessão. Ex: client_credencials
• clientId: identificador do cliente. Ex: 41b44ab9a56440.teste
• clientSecret: chave secreta do cliente. Ex: e9d15cde33024c1494de7480e69b
• scope: escopos registrados com o aplicativo. Ex: vso.profile
• state: usado para gera uma string aleatória e a inclui na solicitação, isso serve para evitar ataques CSRF. Ex: xcoiv98y2kd22vusuye35qq
• code: tipo de concessão código de autorização do cliente. Ex: 4BV8LHVNl49hy5qKF8yyKetGJNjCfJ6K1KvFJn5WSA==
• refreshToken: verificar de tempos em tempos o ID (Access Token), os tokens de acesso expiram rapidamente. Ex: eAW8CpgUcWCDv5lM+G5RwJOvWMnK0VAg1O1nFQjRw==
• contentType: tipo de mídia para o recurso. Ex: application/json

Se escolher essa autenticação, os campos endpoint, grantType, clientId e clientSecret são obrigatórios.

Exemplo apenas do trecho de autenticação oAuthTwo:

 "oAuthTwo": {
    "endpoint": "https://yoursite.azurewebsites.net/oauth/callback",
    "grantType": "client_credentials",
    "clientId": "CBA114E0-02A7-44CC-9D65-2DB588B58DBE",
    "clientSecret": "eyJ0eXAiOiJKV1QiLCjhbGciOiJSUzl1Nils",
    "scope": "vso.profile vso.agentpools",
    "state": "string",
    "code": "",
    "refreshToken": "",
    "contentType": "application/json"
  }

Para atualizar as URLs basta enviar uma nova requisição para o mesmo tipo de evento, pois ele irá sobrescrever o anterior.

📘

Saiba que:

Caso a Celcoin não receba do cliente o status de sucesso no recebimento das notificações. É realizado 10 novas retentativas com intervalo de 10 segundos.

Consultar webhooks

É possível consultar a configuração realizada para recebimento dos webhooks, ou seja, verificar qual URL cadastrada para cada evento. Para isso é necessário realizar um GET na API Consultar webhooks.

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/dda-servicewebhook-webservice/v1/webhook/routes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}'

Modelo de response

{
    "status": 200,
    "body": [
        {
            "typeEventWebhook": "Invoice",
            "url": "https://webhook.site/adf0d812-3e2d-43cc-91be-3d84128d27ab"
        },
        {
            "typeEventWebhook": "Deletion",
            "url": "https://webhook.site/adf0d812-3e2d-43cc-91be-3d84128d27ab"
        },
        {
            "typeEventWebhook": "Subscription",
            "url": "https://webhook.site/adf0d812-3e2d-43cc-91be-3d84128d27ab"
        }
    ]
}

Nessa requisição, o typeEventWebhook indica qual o evento configurado e a url é o endereço definido para receber as notificações do evento especificado anteriormente. Se existir a configuração de mais de um evento, será retornado mais de uma configuração (conforme exemplo acima).

Cadastrar usuário

Para acessar o DDA, o usuário precisa ser cadastrado e dar permissão ao aceitar o termo de adesão. O cadastro do usuário no DDA também é chamado de subscrição ou registro.

Para realizar a subscrição é necessário fazer um POST na API Cadastrar usuário informando nome e documento (CPF ou CNPJ) do usuário. Além disso, o campo clientRequestId é um identificador da transação externo, informado pelo cliente para conseguir identificar a requisição do seu lado.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "23155663049",
  "clientName": "Celcoin Customer",
  "clientRequestId": "0001"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "23155663049",
        "clientRequestId": "0001",
        "responseDate": "2022-11-17T14:03:06.4688394+00:00",
        "status": "PROCESSING",
        "subscriptionId": "bfacff76-de86-4b8d-9797-4ea565b4f60d"
    }
}

Estrutura do response:

A criação da subscrição/registro é assíncrona, ou seja, a API não retorna o sucesso ou erro do registro no momento da requisição. Para saber do sucesso, ou não, do cadastro do usuário é necessário configurar os webhooks para o evento Subscription e assim que o registro alterar o status será enviada a notificação.

Status da Subscrição

• Processing: solicitação recebida e se encontra em processamento (via retorno da API)
• Created: subscrição criada com sucesso (via webhook)
• Error: solicitação de subscrição falhou (via webhook)

Exemplo de notificação de subscrição criada com sucesso:

{
  "body": {
    "document": "23155663049",
    "clientRequestId": "0001",
    "subscriptionId": "bfacff76-de86-4b8d-9797-4ea565b4f60d",
    "clientName": "Celcoin Customer",
    "status": "Created",
    "error": null
  }
}

A atualização de status pode acontecer em média dentro de 24hs em produção, mas no ambiente de teste pode ocorrer com intervalo de tempo maior.

É possível simular uma notificação de status de sucesso e erro no registro, sem a necessidade de aguardar muito tempo para recebimento do webhook, utilizando nossos dados de teste.

Simular cadastro com sucesso

Para simular o status de created com dados armazenados, basta enviar a requisição de subscrição com o CPF "71929784007". Veja exemplo a seguir:

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "71929784007",
  "clientRequestId": "customer_sucess_teste",
  "clientName": "Customer Teste de Sucesso"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "71929784007",
        "clientRequestId": "customer_sucess_teste",
        "responseDate": "2023-01-19T12:51:13.7569799+00:00",
        "status": "PROCESSING",
        "subscriptionId": "37dc8e9b-22b7-4ab2-9cea-630c90a473bb"
    }
}

Notificação enviada:

{
  "body": {
    "document": "71929784007",
    "clientRequestId": "customer_sucess_teste",
    "subscriptionId": "37dc8e9b-22b7-4ab2-9cea-630c90a473bb",
    "clientName": "Mock Client",
    "status": "Created",
    "error": null
  }
}

Como esse CPF está armazenado previamente, não há envio de notificações de boletos para ele. Para esse teste, utilize CPFs (ou CNPJs) diferentes.

Simular cadastro com erro

É possível simular também o status de error com dados armazenados. Para isso, basta enviar a requisição de subscrição com o CPF "26817625025". Veja exemplo a seguir:

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "26817625025",
  "clientRequestId": "customer_erro_teste",
  "clientName": "Customer Teste Erro"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "26817625025",
        "clientRequestId": "customer_erro_teste",
        "responseDate": "2023-01-19T12:55:39.9832855+00:00",
        "status": "PROCESSING",
        "subscriptionId": "c2d29554-7128-4c41-b8c1-d694dbc2bb16"
    }
}

Notificação enviada:

{
  "body": {
    "document": "26817625025",
    "clientRequestId": "customer_erro_teste",
    "subscriptionId": "c2d29554-7128-4c41-b8c1-d694dbc2bb16",
    "clientName": "Mock Client",
    "status": "Error",
    "error": [
      {
        "ErrorCode": "CDDA101",
        "ErrorMessage": "Ocorreu um erro inesperado"
      }
    ]
  }
}

Boletos

As notificações dos boletos serão enviadas a partir do momento que o registro for criado com sucesso (status created). Ou seja, a partir do momento que o CPF/CNPJ tiver sido aprovado no cadastro do DDA, ele já está apto para receber notificações de contas a pagar. Assim que houver registro de um boleto bancário para aquele documento, os webhooks de boletos serão disparados.

📘

Importante:

Ao fazer um novo cadastro de documento no DDA, as notificações dos boletos com o status "Aberto" na Plataforma Centralizada de Pagamentos (PCR) da Núclea, serão enviadas mesmo quando estes foram emitidos antes do cadastro do usuário. Não é possível enviar notificações retroativas de boletos que o status não esteja "Aberto".

Em ambiente de teste é possível simular a geração de boletos para o usuário cadastrado (exceto CPF mockado). Para isso, basta realizar um POST na API de Gerar boleto informando o documento que deseja receber notificação. É possível informar mais de um documento e o limite máximo é de 20 documentos por requisição. Vale lembrar que os documentos precisam ser separados por vírgula e devem estar dentro de aspas, sem pontos e traços.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/dda-serviceinvoice-webservice/v1/invoice/register' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "document": [
     "28935923095","85429850012"
  ]
}'

Modelo de response:

{
    "status": 201,
    "body": [
        {
            "document": "28935923095",
            "status": "Success"
        },
        {
            "document": "85429850012",
            "status": "Success"
        }
    ]
}

No exemplo acima será enviada uma notificação de boleto para o usuário de CPF 28935923095 e uma notificação para o usuário de CPF 85429850012.

Caso seja enviado um documento que não esteja cadastrado (status CREATED) no DDA, que tenha sido excluído (status INACTIVE) ou qualquer situação semelhante, o retorno será falha. Exemplo:

 {
    "status": 201,
    "body": [
        {
            "document": "64172598030",
            "status": "Fail"
        }
    ]
}

Caso queria enviar mais de uma notificação para o mesmo documento, basta eneviar o documento mais de uma vez, respeitando o limite máximo de 20 dados. Exemplo:

 "document": [
    "28935923095","28935923095","28935923095","28935923095"
  ]

Nesse exemplo serão enviadas 4 notificações. Se caso enviar mais de 20 documentos na requisição, seria retornado erro 400 com a seguinte mensagem:

{
    "status": 400,
    "erro": {
        "errorCode": "CDDA115",
        "message": "A requisição possui um limite de até 20 documentos"
    }
}

Segue exemplo de uma notificação de boleto:

{
  "body": {
    "registerData": {
      "addresseeBank": {
        "assignor": "",
        "ispb": 60701190,
        "code": "001"
      },
      "originalBeneficiary": {
        "personType": "J",
        "documentNumber": "123456789010005",
        "name": "Fantasy Name",
        "fantasyName": "Fantasy Name"
      },
      "payer": {
        "personType": "F",
        "documentNumber": "23075751030",
        "name": "Celcoin 00 Teste",
        "fantasyName": ""
      },
      "dueDate": "2023-03-09T17:56:29.1423434",
      "dueDateRegister": null,
      "hasDiscount": true,
      "hasInterest": true,
      "description": "Fixed DueDate",
      "originalValue": 559989,
      "digitable": "892553661673295756645011952605835108625025111969",
      "barCode": "892553661673295756645011952605835108625025111969",
      "status": "Aberto",
      "paymentSituation": "Boleto de pagamento encontrado na base centralizada e cliente beneficiário apto",
      "transactionId": "5c361b6c-b9aa-48b9-816a-ef5ade51edd3"
    }
  }
}

Para saber de qual usuário a notificação de boleto se refere, basta utilizar os campos do objeto "payer". O campo documentNumber dentro do objeto "payer" é o CPF ou CNPJ do usuário cadastrado.

Estrutura da notificação:

Status dos boletos

Os boletos podem retornar sete diferentes status. São eles:

📘

Saiba que:

Nessa primeira etapa você pode efetuar o pagamento do boleto com nossa API de pagamento de contas. Veja como fazer aqui.

Excluir usuário

É possível remover um usuário do DDA caso seja necessário. Para isso, basta realizar um DELETE na API de Excluir usuário informando o documento (CPF ou CNPJ) e o identificador externo clientRequestId.

Modelo de request:

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "23155663049",
  "clientRequestId": "0001"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "23155663049",
        "clientRequestId": "0001",
        "responseDate": "2023-01-18T19:54:16.6647364+00:00",
        "status": "PROCESSING",
        "subscriptionId": "37c571d7-a594-4a11-8629-2e993beecf5d"
    }
}

Estrutura do response:

Nessa solicitação ocorre o mesmo comportamento da requisição de registro, ou seja, a chamada não é síncrona. Para saber se a exclusão ocorreu com sucesso ou não, é necessário configurar os webhooks para o evento Deletion e assim que a exclusão alterar o status será enviada a notificação. O status Inactive indica exclusão efetuada com sucesso. Veja todos os status:

Status da Exclusão

• Processing: solicitação recebida e se encontra em processamento (via retorno da API)
• Inactive: solicitação de exclusão do registro efetuada com sucesso (via webhook)
• Inactive_failed: solicitação de exclusão do registro falhou (via webhook)

Exemplo de notificação de exclusão efetuada com sucesso:

{
  "body": {
    "document": "26984598087",
    "clientRequestId": "0001",
    "subscriptionId": "37c571d7-a594-4a11-8629-2e993beecf5d",
    "clientName": "Celcoin Cliente 1",
    "status": "Inactive",
    "error": null
  }
}

Vale ressaltar que caso a solicitação de exclusão retorne status Inactive_failed, significa que a exclusão falhou, então o cliente vai continuar registrado no DDA. A exclusão só vai acontecer quando o status retornado for Inactive.

A atualização de status pode acontecer em média dentro de 24hs em produção, mas no ambiente de teste pode ocorrer com intervalo de tempo maior.

É possível simular uma notificação de status de sucesso e erro na exclusão, sem a necessidade de aguardar muito tempo para recebimento do webhook, utilizando nossos dados de teste.

Simular exclusão com sucesso

Para simular o status de inactive com dados armazenados, basta enviar a requisição de exclusão com o CPF "71929784007". Veja exemplo a seguir:

Modelo de request:

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "71929784007",
  "clientRequestId": "customer_teste"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "71929784007",
        "clientRequestId": "customer_teste",
        "responseDate": "2023-01-12T13:54:58.0480445+00:00",
        "status": "PROCESSING",
        "subscriptionId": "d937c0b0-91ef-4c1a-a8e9-ea9488607d8a"
    }
}

Notificação enviada:

{
  "body": {
    "document": "71929784007",
    "clientRequestId": "customer_teste",
    "subscriptionId": "d937c0b0-91ef-4c1a-a8e9-ea9488607d8a",
    "clientName": "Mock Client",
    "status": "Inactive",
    "error": null
  }
}

Simular exclusão com erro

Para simular o status de inactivateFailed com dados armazenados, basta enviar a requisição de exclusão com o CPF "26817625025". Veja exemplo a seguir:

Modelo de request:

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/dda-subscription-webservice/v1/subscription/Register' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "document": "26817625025",
  "clientRequestId": "teste_error"
}'

Modelo de response:

{
    "status": 201,
    "body": {
        "document": "26817625025",
        "clientRequestId": "teste_error",
        "responseDate": "2023-01-12T13:55:47.4817623+00:00",
        "status": "PROCESSING",
        "subscriptionId": "f97a7cb0-57f5-4661-9aa6-c64de670918c"
    }
}

Notificação enviada:

{
  "body": {
    "document": "26817625025",
    "clientRequestId": "teste_error",
    "subscriptionId": "f97a7cb0-57f5-4661-9aa6-c64de670918c",
    "clientName": "Mock Client",
    "status": "InactivateFailed",
    "error": [
      {
        "ErrorCode": "CDDA101",
        "ErrorMessage": "Ocorreu um erro inesperado"
      }
    ]
  }
}