Pagamentos de contas

Boletos, concessionárias e tributos

O que a API faz?

A API de Pagamentos de Contas do serviço de Banking-as-a-service da Zoop permite que seus clientes paguem boletos e contas geradas por diferentes bancos e instituições financeiras se eles estiverem devidamente registrados na CIP (Câmara Interbancária de Pagamentos) para pagamento em rede bancária conveniada, sendo possível também o pagamento de contas de concessionárias, ficha de compensação, DARF e GPS.

Como posso começar a utilizar?

Para usar o serviço de pagamentos de contas através da Zoop, é necessário:

  • Ter uma conta de pagamentos ativa;

  • Criar uma nova operação de pagamento de conta através do serviço payments autorizando assim um débito no valor informado na conta zoop do pagador;

  • Após confirmação ou falha do pagamento realizado pelo serviço da Zoop, seu sistema é notificado.

Disponibilizamos um serviço para consulta e validação dos dados de pagamento a partir de um número válido de código de barras.

Através dessa consulta de validação é possível recuperar:

  • valor do boleto;

  • tipo (se normal ou registrado);

  • data limite de vencimento;

  • data limite para pagamento;

  • horário mínimo e máximo para aceitar o pagamento;

  • se a data e horário é válida para pagamento.

O serviço retorna também automaticamente para boletos registrados o valor discriminado de desconto, juros e multa, incluindo o valor total a ser pago pelo boleto já acrescido de juros, multa e desconto, que deve ser informado para pagamento.

O que posso pagar com a API de pagamentos?

Podemos dividir os tipos de contas que a API de pagamentos em duas categorias:

Normal

NPC

Títulos de pagamento como conta de água, luz, cartão de crédito etc

Registrado na CIP

Não tem data de vencimento

Possui data de vencimento

Normal: este tipo de fatura geralmente vem em uma base mensal, como contas de telefone celular, luz, gás, impostos, aluguel e etc. Nesse tipo de boleto, a janela de tempo geralmente vai das 7:30 (GMT-3) às 16:00 (GMT-3). Outro aspecto importante dos boletos normais é que após o vencimento não haverá valor extra na forma de multas ou juros a serem pagos, porém, na próxima fatura, o valor será acrescido de acordo com os valores dos dias não pagos.

NPC: Esse tipo de boleto é um boleto usual criado por um banco para pagar uma fatura de cartão de crédito ou pagar uma dívida a uma empresa, por exemplo. Nesse tipo de fatura, a janela de tempo geralmente vai das 07:00 (GMT-3) às 20:30 (GMT-3). Outro aspecto importante das contas dos NPCs é que após a data de vencimento eles podem estar disponíveis para pagar, porém, agora sujeitos a multas e juros.

Regras de validação e pagamento

Para boletos de concessionária que no serviço de validação são caracterizado como tipo "normal" o vencimento será sempre no dia em que o mesmo será pago, ou seja, ele não possui uma data limite de pagamento, a diferença é que a taxa será cobrada no próximo boleto.

Exemplo: Pagamento de conta de luz 10 dias após o vencimento. Na próxima conta terá a adição do valor da multa/juros referente ao atraso.

Os campos discount e interest são de preenchimento opcional no serviço de pagamento de contas, servindo apenas para consulta e visualização futura, devendo sempre ser informado o valor final do boleto (já calculado pelo total_amount do serviço de validação).

Exemplo: Boleto pago com amount R$ 3,50 (sendo R$ 5,00 de valor original, descontado R$ 2,00 e acrescido de R$ 0,50 de juros)

Ao se tentar pagar boletos fora da janela de pagamento (horários) , ou fora dos dias úteis, o serviço de pagamentos de contas informará que o horário para pagamento não é permitido (recomenda-se que o desenvolvimento já impeça o pagamento na validação).

Para o boleto registrado o tipo é identificado como "registered", sendo possível o pagamento independente de estar vencido ou não. Se no registro do boleto foi inserido juros, multa, mora, para este cenário, o serviço de validação retornará estes valores, que devem ser repassados no pagamento.

O campo payment_limit_date do serviço de validação indica a data limite de pagamento de boleto registrado (só serão aceitos pagamentos até esta data) - o que é diferente do due_date )data de vencimento) , pois é possível pagar boletos vencidos. Pagamentos realizados após esta data serão recusados pelo serviço de pagamentos.

O campo computed_bill_values, retornado na validação de boletos registrados, discrimina os juros, multa, mora, etc.. O valor total com desconto ou multa a ser pago é retornado em total_amount. que deve ser o valor final a ser pago no serviço de pagamentos.

Exemplo: na tentativa de pagamento de um boleto de R$12 + juros de R$ 3, se o pagamento for somente de R$12, (sem os juros) o banco irá recusar e o pagamento será estornado.

Somente serão efetuados pagamentos de boletos e contas com o valor mínimo de R$1,10.

Janelas de Pagamentos

Normal e Registered (NPC)

  • Geralmente, das 7h às 16:00h. (Boletos emitidos pelo Bradesco, o horário será estendido ate 22h30)

Tributos:

  • Geralmente, das 7:30 às 22:30h.

Obs.: Se o pagamento ocorrer na janela de tempo referente ao pagamento, a liquidação ocorre em até 3 dias úteis. Porém, se o pagamento ocorrer fora da janela de pagamento, a transação não ocorrerá, sendo necessário tentar novamente no próximo dia útil.

Importante: Apenas dias úteis. A API de Pagamentos não funciona nos finais de semana e nem feriados (conforme calendário da FEBRABAN ). Portanto, o pagamento deve ocorrer em dias úteis. Os pagamentos executados fora das janelas de pagamento serão estornados.

Status do pagamento

Estados possíveis para um boleto pago através da API de pagamentos de contas:

  • Created: Pagamento criado com sucesso ficando pendente a confirmação junto instituição financeira

  • Confirmed: Pagamento confirmado com sucesso junto instituição financeira

  • Failed: Pagamento não foi autorizado ou rejeitado pela instituição financeira do recebedor

Código de retorno da API

A API retorna os códigos de resposta (responses) positivos e negativos sobre a validação do boleto para liquidação. Aqui temos os retornos mais comuns. Exemplo:

Código

Descrição

200 Ok

A chamada para pagar a conta foi bem sucedida e enviada para liquidação

400 Bad Request

A requisição é inválida, em geral está com caracteres inválidos do convencional de um boleto

403 Forbidden

O acesso a API está bloqueado ou o usuário está bloqueado

409 Processing Error

Erro em processar código de barras. Ex: Não registrado na CIP, vencido/cancelado, já pago

422 Unprocessabe Entity

A requisição é válida, mas os dados passados não são válidos. Ex: Banco não registrado na CIP, Valor enviado diferente do valor cadastrado no código de barras

424 Too Maby Requests

Usuário atingiu o limite de requisições

500 Internal Server Error

Houve um erro interno do servidor ao processar a requisição

Detalhamento dos retornos de erros do boleto

Status Code

Mensagem em inglês

Mensagem em português

400

Param barcode is required, should contain only numbers, be at least 35 characters and maximum length of 60. Check the Febraban standard

O Parâmetro barcode é obrigatório, deve conter apenas números, ter no mínimo 35 caracteres e comprimento máximo de 60. Verifique o padrão da Febraban

409

Failed to process barcode validation. Unregistered barcode or payment already paid

Falha ao processar a validação do código de barras. Código de barras não registrado ou pagamento já pago

409

Barcode had its payment deadline exceeded

Data de vencimento do boleto expirada

409

Barcode unregistered, cancelled or payment already paid

Código de barras não registrado, cancelado ou pagamento já efetuado

422

Bank not registered at CIP

Banco não registrado na CIP

422

Payment amount differs from bankslip

O valor do pagamento difere do boleto

422

Barcode not registered at CIP

Código de barras não registrado na CIP

422

Payment request not allowed for this time

Pagamento não permitido neste horário

422

Failed to execute payment transaction

Falha ao executar a transação de pagamento

422

This payment slip was already processed and can no longer be paid

Não é possível realizar o pagamento. O boleto já foi pago ou foi cancelado

422

Barcode had its payment expiration date exceeded

Data de vencimento do boleto expirada

503

It was not possible to validate the bank slip. Try again later *

Não foi possível validar o boleto. Tente novamente mais tarde *

* Não será disponibilizada uma mensagem de retorno quando o serviço estiver indisponível

Exemplo de response

{
"status": "unprocessable_entity",
"type": "invalid_state",
"message": " Barcode unregistered, cancelled or payment already paid ",
"category": "business",
"status_code": 422
}

Convênios aceitos para pagamento de contas

Dicas importantes

O que é necessário para pagar uma conta?

Para pagar uma conta, é necessário validar o código de barras antes de pagá-la. Esse processo é importante porque nossa API de pagamentos precisa do valor exato pago na fatura e o processo de validação mostra o total de descontos, multas e juros, bem como o valor total a cobrar. Se o pagamento ocorrer com o valor incorreto, o banco recusará o pagamento e o dinheiro será devolvido. O processo de validação também mostra a data limite de pagamento (quando existe). O pagamento desta fatura somente será aceito até essa data, que pode ser diferente do seu vencimento, uma vez que é possível pagar contas vencidas.

Liquidação de contas

A liquidação ou situação final de uma fatura pode demorar até 72h (3 dias úteis) para que haja uma resposta final sobre o andamento da transação devido a compensação bancária.

O que são convênios?

Assim como os boletos, os títulos e convênios também possuem código de barras a serem lidos ou digitados. O que diferencia esse tipo de cobrança é que ela não é emitida por uma instituição financeira, mas sim pela própria empresa que, normalmente, são concessionárias de serviços.

Os títulos e convênios são popularmente conhecidos como contas. Os serviços mais populares cobrados são água, luz, telefone, TV a cabo e gás. Outra diferença em relação aos boletos, é que esse tipo de pagamento, caso feito com atraso, não acarreta juros imediatos. O acréscimo só é cobrado no mês seguinte.

O padrão é de 4 sequências de algarismos sempre com o último número da sequência sendo um dígito isolado. Ao todo, são 48 caracteres dispostos como no exemplo abaixo:

12345678912-3 12345678912-3 12345678912-3 12345678912-3

O pagamento dessas cobranças também pode ser feito por meio dos bancos conveniados ou casas lotéricas. Entretanto, como os vencimentos são os mesmos para todos os usuários desses serviços, para evitar que esses locais fiquem cheios com filas, os bancos criaram a possibilidade de pagamento por internet banking, aplicativos e caixas eletrônicos.

É importante lembrar que ainda assim, todos esses pagamentos podem continuar a serem feitos da maneira tradicional.

Diferença entre Linha digitável x Código de Barras

Apesar de terem formatos diferentes, as informações da Linha Digitável e do Código de Barras são as mesmas, tais como: número do banco, moeda, data de vencimento, valor, etc. No boleto bancário de cobrança, a Linha Digitável tem 47 dígitos e o Código de Barras tem 44 dígitos.

A Linha Digitável: Exemplo de uma Linha Digitável e de um Código de Barras com o mesmo significado. Note que os números com cores vermelhas acima também constam no Código de Barras abaixo, mas em ordem diferente.

O Código de Barras: Exemplo do Código de Barras com o mesmo significado da Linha Digitável acima:

Detalhamento da Linha digitável

A representação numérica do Código de Barras é distribuída em 5 partes, sendo os 3 primeiros consistidos por um dígito verificador e, entre cada campo, espaço equivalente a uma posição. No quarto campo é indicado, isoladamente, o dígito verificador do Código de Barras.

  • Posição 01-03 = identificação do banco (001 = banco do brasil)

  • Posição 04-04 = código da moeda (9 = real)

  • Posição 05-09 = 5 primeiras posições do campo livre

  • Posição 10-10 = dígito verificador do primeiro campo

  • Posição 11-20 = 6º a 15º posições do campo livre

  • Posição 21-21 = dígito verificador do segundo campo

  • Posição 22-31 = 16º a 25º posições do campo livre

  • Posição 32-32 = dígito verificador do terceiro campo

  • Posição 33-33 = dígito verificador geral

  • Posição 34-37 = vencimento (3737 = 31/12/2007)

  • Posição 38-47 = valor do boleto (100 = R$1,00)

(*) Os campos livres são utilizados pelos bancos de acordo com as especificações internas do próprio banco emissor do boleto, mas, geralmente, informam o número do prefixo da agência bancária, o código da carteira (com registro, rápida, caucionada, etc), o “nosso número” e a conta de relacionamento do beneficiário.

O que é a Febraban?

A FEBRABAN representa o setor bancário e atua regularizando e fomentando o mercado financeiro-econômico do país. A FEBRABAN determina as normas e regula a emissão e pagamento de boletos a partir da Lei do Boleto Bancário de 2018 e também estabelece os padrões de layout que devem ser adotados, tudo visando o aumento do controle e da segurança no processamento dessa forma de pagamento. Como Pagamento de Contas é dependente de compensação bancária, seguimos o calendário de atividade bancária dessa instituição.