DDA

DDA: visão geral

O DDA (Débito Direto Autorizado) mostra, num só lugar, os boletos registrados no CPF/CNPJ da sua conta, sem esperar o boleto chegar por e-mail ou correio.

A ValidaPay exibe esses boletos; ela não os emite nem os recebe. O pagamento acontece no banco do sacado, com a linha digitável. Não existe rota para pagar um boleto do DDA. O recurso também não está disponível em sandbox: qualquer rota de DDA com conta de sandbox devolve 403 DDA_NOT_AVAILABLE_IN_SANDBOX.

Como funciona

A conta se inscreve uma vez. A partir daí, os boletos emitidos contra aquele documento chegam por webhook e ficam disponíveis na listagem.

POST /v1/dda/subscription inscreve o documento da conta. A inscrição nasce em PROCESSING.
Alguns minutos depois chega dda.subscription.updated com ACTIVE, e a listagem libera.
Os boletos já registrados no documento chegam em rajada, logo após a confirmação.
Cada boleto novo e cada mudança de situação disparam dda.invoice.received.

A inscrição é por documento, não por conta. Se o CPF/CNPJ já estiver inscrito, a chamada devolve 409 DDA_ALREADY_SUBSCRIBED.

Estados da inscrição

Status	O que significa
`PROCESSING`	Inscrição enviada, aguardando confirmação
`ACTIVE`	Inscrição confirmada; boletos visíveis
`ERROR`	Inscrição recusada; errorMessage traz o motivo
`INACTIVATING`	Cancelamento solicitado, aguardando confirmação
`INACTIVE`	Cancelamento confirmado
`INACTIVATE_FAILED`	Cancelamento recusado

A listagem exige ACTIVE, INACTIVATING ou INACTIVATE_FAILED. Nos outros estados devolve 403 DDA_SUBSCRIPTION_NOT_ACTIVE. Desativar é assíncrono e pode levar horas; enquanto está em INACTIVATING, os boletos continuam visíveis.

Situação do boleto

Status	Quando acontece
`OPEN`	Boleto em aberto
`PAID`	Liquidado, intra ou interbancário
`CANCELLED`	Baixado sem pagamento: pedido do beneficiário, decurso de prazo, protesto ou pedido da instituição

O boleto chega com uma de sete situações distintas, reduzidas a esses três estados: as duas de liquidação viram PAID, as quatro demais baixas viram CANCELLED.

O DDA é uma vitrine, não um extrato de pagamentos. Recomendamos não usá-lo como fonte para definir se um boleto foi pago. Use-o para visibilidade, e o seu conciliador para liquidação.

Vencimento e prazo de pagamento

Campo	Significado
`dueDate`	Data de vencimento do boleto
`overdueDate`	Data limite para pagamento

Um boleto vencido continua OPEN: não existe status de vencido. Para saber se ainda dá para pagar, compare a data de hoje com overdueDate, não com dueDate. Passado o overdueDate, o banco recusa e a cobrança passa a ser direto com o beneficiário.

Listagem e paginação

GET /v1/dda/invoices aceita status, startDate e endDate (por vencimento), além de limit (1 a 100, padrão 50).

A paginação é por cursor: pagination.lastKey volta no corpo e é reenviado como lastKey na requisição seguinte. Quando hasMore é false, lastKey vem null. Cursor adulterado devolve 400 INVALID_CURSOR.

Eventos

Evento	Quando
`dda.subscription.updated`	A inscrição no DDA mudou de estado. Chega alguns minutos após a ativação e pode levar horas no cancelamento.
`dda.invoice.received`	Boleto registrado no CPF/CNPJ da conta. Enviado na primeira vez e sempre que o `status` muda; reenvio sem mudança de situação não dispara o evento.

Erros

Código	HTTP	Quando
`DDA_NOT_AVAILABLE_IN_SANDBOX`	403	Qualquer rota de DDA com conta de sandbox
`DDA_ALREADY_SUBSCRIBED`	409	Documento já inscrito
`DDA_SUBSCRIPTION_PROCESSING`	409	Inscrição anterior ainda em processamento
`DDA_SUBSCRIPTION_NOT_FOUND`	404	Consulta sem inscrição existente
`DDA_SUBSCRIPTION_NOT_ACTIVE`	403 / 404	Listagem sem inscrição ativa (403) ou cancelamento sem inscrição ativa (404)
`INVALID_CURSOR`	400	lastKey malformado
`DDA_PROVIDER_ERROR`	400	Falha de comunicação ao consultar o DDA

Essa página foi útil?