Pagamentos de contas

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 três categorias:

Boletos de Cobrança: Esse tipo de fatura é 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 23:00 (GMT-3).

Concessionárias: Esse 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 23:59 (GMT-3).

Tributos: Esse tipo de fatura é um boleto criado por algum órgão do governo e geralmente vem em pagamento único, como DARF, SEFAZ e etc.
Boletos de tributos tem até 30 dias para serem pagos.

Nesse tipo de fatura, a janela de tempo geralmente vai das 7:30 (GMT-3) às 23:00 (GMT-3).

Existem tributos com janelas próprias de pagamento.

Pagamento de contas

Regras de validação e pagamento

Para boletos de concessionária que no serviço de validação são caracterizados 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

Boletos de Cobrança até às 23h;

Concessionárias até às 23h59min;

Tributos com código de barras até às 23h (exceto em casos de janela específica);

Fallback

Normal e Registered (NPC)

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

Tributos:

  • Geralmente, das 7h30min às 22h30min.

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

Comprovantes de pagamento

Os comprovantes de pagamento são gerados automaticamente pela Zoop e podem ser baixados através de nossa API.
Os comprovantes seguem a regulação da FEBRABAN, mantendo o layout especifico para cada tipo de boleto.

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ódigoDescrição
200 OkA chamada para pagar a conta foi bem sucedida e enviada para liquidação
400 Bad RequestA requisição é inválida, em geral está com caracteres inválidos do convencional de um boleto
403 ForbiddenO acesso a API está bloqueado ou o usuário está bloqueado
409 Processing ErrorErro em processar código de barras. Ex: Não registrado na CIP, vencido/cancelado, já pago
422 Unprocessabe EntityA 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 RequestsUsuário atingiu o limite de requisições
500 Internal Server ErrorHouve um erro interno do servidor ao processar a requisição

Detalhamento dos retornos de erros do boleto

Status CodeMensagem em inglêsMensagem em português
400Param barcode is required, should contain only numbers, be at least 35 characters and maximum length of 60. Check the Febraban standardO 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
409Failed to process barcode validation. Unregistered barcode or payment already paidFalha ao processar a validação do código de barras. Código de barras não registrado ou pagamento já pago
409Barcode had its payment deadline exceededData de vencimento do boleto expirada
409Barcode unregistered, cancelled or payment already paidCódigo de barras não registrado, cancelado ou pagamento já efetuado
422Bank not registered at CIPBanco não registrado na CIP
422Payment amount differs from bankslipO valor do pagamento difere do boleto
422Barcode not registered at CIPCódigo de barras não registrado na CIP
422Payment request not allowed for this timePagamento não permitido neste horário
422Failed to execute payment transactionFalha ao executar a transação de pagamento
422This payment slip was already processed and can no longer be paidNão é possível realizar o pagamento. O boleto já foi pago ou foi cancelado
422Barcode had its payment expiration date exceededData de vencimento do boleto expirada
503It 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
{
    "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 importante

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.