Api de Geração de Boletos

Visão Geral

Com a API de Geração de Boletos, sua aplicação pode gerar boletos de cobrança com datas de vencimento personalizadas, ou seja, você poderá escolher em quais datas serão efetuadas as cobranças dos produtos/serviços prestados.

Essa demanda foi desenvolvida especificamente para atender um público que necessita efetuar cobranças recorrentes ou de alto valor para parcelamento, como planos de saúde, academias, condomínios, clubes, ticketeiras, entre outros - independente se suas vendas são online ou presenciais.

Você poderá encaminhar aos seus compradores os boletos de cobrança no modelo de carnê, ou ainda disponibilizá-los online em seu site. Você poderá também enviar o códigos de barras através dos canais mais aderentes ao seu negócio, como aplicativos, redes sociais e e-mails personalizados, por exemplo.

Os boletos gerados pela API de Geração de Boletos são registrados e estão em compliance com as novas regras do mercado.

Como Funciona?

Desenvolvida para atender à necessidade de gerar cobranças recorrentes por boletos, a API de geração de boletos não permite vínculo com planos da API de Pagamento Recorrente Transparente (via cartão). Aqui, as cobranças não ocorrem de forma automática e dependem das chamadas feitas pela aplicação do vendedor.

As chamadas dessa API fornecem uma configuração que possibilita criar cobranças em lote de boletos no modelo de carnê, ou gerar os boletos individualmente a cada período de cobrança.

Essa flexibilidade depende de seu modelo de negócio, caso seus valores de cobranças sejam variáveis a cada ciclo de período, por exemplo.

É ideal que sua aplicação esteja apta para suportar tempo de resposta de até 1 minuto, pois a depender da quantidade de boletos a serem gerados, sua aplicação pode retornar time out enquanto ainda os boletos estiverem sendo gerados no PagSeguro.

NOTA: Os boletos gerados pelo PagSeguro cobram dos compradores uma tarifa aplicada para cobrir custos de gestão de risco do meio de pagamento em questão. Portanto os valores informados nas chamadas dessa API terão um acréscimo de R$ 1,00 referente a essa tarifa.

Parâmetros da API

Pré Modulagem

Deve ser enviada uma chamada de API para cada comprador, podendo conter nesta mesma chamada todas as parcelas necessárias para este cliente.

A pré modulagem permite configurar qual a primeira data de cobrança, quantas vezes a cobrança será repetida (por períodos mensais), o valor de cada cobrança e a personalização do campo “instruções” do boleto.

Veja a seguir, detalhes dos parâmetros para geração dos boletos.

Nome Campo Descrição
reference Campo destinado a controles internos do vendedor.
Tamanho máximo: 200 caracteres. Este parâmetro é opcional.
firstDueDate Formato: aaaa-mm-dd

Data de vencimento para qual será gerado o primeiro boleto - permitido 1 dia à partir da data presente até D+30.

Se o parâmetro numberOfPayments > 1, os próximos vencimentos seguirão com a mesma data informada no na data dd nos períodos subsequentes.

Para meses onde não existirem a data informada, será considerado sempre um dia anterior.
numberOfPayments Informar a quantidade de boletos a serem gerados para cada comprador.

À partir da primeira data de vencimento informada no campo firstDueDate, será gerada a quantidade de boletos informados neste campo, com vencimentos para os períodos subsequentes.

Exemplo:
firstDueDate: 2017-10-20
numberOfPayments: 4
periodicity: monthly

Boletos gerados:
1. Vencimento em: 20/10/2017
2. Vencimento em: 20/11/2017
3. Vencimento em: 20/12/2017
4. Vencimento em: 20/01/2018

Permitido preencher de 1 a 12.
periodicity Frequência na qual os boletos serão gerados para cobrança.
Necessário informar: monthly
Atualmente a chamada não aceita nenhum outro valor diferente.
amount Informar o valor em reais a ser cobrado em cada boleto. Mínimo 5.00 e máximo 1000000.00
Formato: decimal, com duas casas decimais separadas por ponto (ex: 1234.56)
instructions Campo instruções do boleto, personalizado para uso do vendedor, restrito a 100 caracteres.
description Descrição do produto objeto da cobrança.
Campo alfanumérico detalhado no extrato PagSeguro do comprador.
Tamanho máximo: 100.
customer Dados pessoais do comprador, descrito na tabela customer abaixo
address Dados de endereço do comprador, descritos na tabela address abaixo. Este parâmetro é opcional.
notificationURL URL para recebimento de notificação. Realiza validação de url válida.
Tamanho máximo: 255. Este parâmetro é opcional.

Dados pessoais e de endereço do comprador

Como estamos tratando de boletos registrados, os dados pessoais são obrigatórios.

Os dados de endereço são opcionais, porém a partir do momento que o elemento address é informado, todos os sub-parâmetros dele são obrigatórios.

Estes devem ser informados aninhados dentro dos parâmetros customer e address da tabela anterior.

Parâmetros do elemento customer

Parâmetro Sub-Parâmetro Descrição
document type Tipo do documento a ser informado, pode ser “CPF” ou “CNPJ”
value Número do documento indicado no campo anterior.
Formato: de 11 a 14 dígitos.
name Nome completo ou Razão Social do comprador do produto /serviço referente ao boleto gerado.
Formato: Campo alfanumérico livre, com no mínimo duas sequências de strings.
Tamanho máximo: 50 caracteres.
email E-mail do cliente.
Formato: Campo alfanumérico sendo um e-mail válido (p.e., usuario@site.com.br)
Tamanho máximo: 60 caracteres.
phone areaCode DDD do comprador.
Formato: Um número de 2 dígitos correspondente a um DDD válido (p.e., “11”)
number Telefone do consumidor.
Formato: Um número entre 8 e 9 dígitos sem traços ou pontos.

Parâmetros do elemento address

Parâmetro Descrição
postalCode CEP sem traços ou pontos.
Formato: Um número de 8 dígitos, p.e. 01046010.
street Nome da rua.
Formato: Campo alfanumérico livre.
Tamanho máximo: 160 caracteres.
number Número.
Formato: Campo alfanumérico livre.
Tamanho máximo: 20 caracteres.
district Bairro.
Formato: Campo alfanumérico livre.
Tamanho máximo: 60 caracteres
complement Complemento.
Formato: Campo opcional alfanumérico livre.
Tamanho máximo: 40 caracteres
city Cidade.
Formato: Campo alfanumérico livre. Deve ser um nome válido de cidade do Brasil.
Tamanho máximo: 60 caracteres.
state Estado.
Formato: Duas letras, representando a sigla.

Exemplo de envio JSON

{
    "reference": "PEDIDO123",
    "firstDueDate": "2017-09-14",
    "numberOfPayments": "4",
    "periodicity": "monthly",
    "amount": "19.87",
    "instructions": "juros de 1% ao dia e mora de 5,00",
    "description": "Assinatura de Sorvete",
    "customer": {
        "document": {
            "type": "CPF",
            "value": "00000000000"
        },
        "name": "Alini QA",
        "email": "compradoralini@xpto.com.br",
        "phone": {
            "areaCode": "11",
            "number": "80804040"
        },
        "address": {
            "postalCode": "01046010",
            "street": "Av. Ipiranga",
            "number": "100",
            "district": "Republica",
            "city": "Sao Paulo",
            "state": "SP"
        }
    }
}

Retornos

A API irá retornar o código da transação gerada no PagSeguro, a URL do boleto online, a linha digitável do código de barras e a data vencimento do boleto.

Com essas informações você pode optar por enviar os boletos online, imprimi-los, ou até mesmo incluir o código de barras no aplicativo de sua empresa.

Para consultar o status do pagamento das transações e outros dados, você deve integrar com integração com API de Notificações.

Exemplo de Retorno JSON

{
    "boletos": [
        {
            "code": "6A91AC74-D6BB-45CB-BC04-A6EB855A131B",
            "paymentLink": "https://pagseguro.uol.com.br/checkout/payment/booklet/print.jhtml?c=df0597592d53e1007805153628f83d667d52a67f15bed3e65f036d22602c3fe1f777c423b8409b2e",
            "barcode": "03399557345480000000998765401025954420000030050",
            "dueDate": "2017-09-14"
        },
        {
            "code": "21331CF4-7470-48F0-AFC3-95F10C2A48E7",
            "paymentLink": "https://pagseguro.uol.com.br/checkout/payment/booklet/print.jhtml?c=60ae9af4f314f9f4ddc5442cfd6b951bd1087ef363dc3aefbaa1f7e39dddb0f8696572d0f19ef49c",
            "barcode": "03399557345480000000998765401025954420000030050",
            "dueDate": "2017-10-14"
        },
        {
            "code": "94AE93E6-C91F-495D-9B54-6E1A8F8CC684",
            "paymentLink": "https://pagseguro.uol.com.br/checkout/payment/booklet/print.jhtml?c=273e997cf68be8a94fd332ba845321e6c8894b75eb930814494faf47e008e51f4b76c88f99dcd39e",
            "barcode": "03399557345480000000998765401025954420000030050",
            "dueDate": "2017-11-14"
        },
        {
            "code": "8FC514FD-36CC-4A3E-8913-F3AFA37E2391",
            "paymentLink": "https://pagseguro.uol.com.br/checkout/payment/booklet/print.jhtml?c=c1bf49771e9f017eede2158c819733f5606cd2cc2eb660d4d0bc70a2759da5f14b26d12a5db6cec1",
            "barcode": "03399557345480000000998765401025954420000030050",
            "dueDate": "2017-12-14"
        }
    ]
}

Segunda Via

Para emissão de 2ª via do boleto, é necessário que o vendedor acesse sua conta PagSeguro e:

  • Acesse o Extrato de Transações
  • Localize a transação desejadae entre nos detalhes desta
  • Clique no link: Gerar 2ª via do boleto.

Se o boleto não estiver vencido, é possível reabrir o boleto já criado em formato PDF. Porém, se estiver vencido, um novo boleto será gerado com data de vencimento para 3 dias adiante.

Atenção: Não é possível obter o número do código de barras por meio do painel.

Existe um prazo máximo para esta geração de boleto vencido. Ele pode ser configurado, juntamente com a data de vencimento de novo boleto e diferenciação ou não de dias úteis ou corridos. Consulte seu gestor comercial ou entre em contato com a Central de Relacionamento.

Gestão de Boletos

Para ter controle e fazer a gestão de seus boletos gerados, pagos e pendentes, é necessária a integração com API de Notificações.

Chamadas à API

Autenticação

Este modelo utiliza o e-mail e token do vendedor como forma de autenticação. Os parâmetros devem ser passados ao fim da URL do serviço, conforme exemplo abaixo:

Ex: https://{caminho do serviço}?email={seu email}&token={seu token}

Por exemplo, para fazer uma chamada ao serviço, supondo que o seu email seja a@b.com e o seu token seja 123ABC, a url de chamada deve ficar da seguinte forma:

https://ws.pagseguro.uol.com.br/recurring-payment/boletos?email=a@b.com&token=123ABC

Para saber qual é o seu token, consulte o seu Painel.

Autenticação para Modelo de Aplicações

Este modelo de autenticação é voltado para sistemas que utilizam o modelo de aplicações do PagSeguro. A autenticação neste caso utiliza o ID e a chave da aplicação do vendedor.

Para algumas chamadas também é necessário o código de autorização do vendedor. Os parâmetros devem ser passados ao fim da URL do serviço, conforme exemplo abaixo:

Ex: https://{caminho do serviço}?appId={id da aplicação}&appKey={chave da aplicação}&authorizationCode={código de autorização}

Para verificar as suas aplicações cadastradas, consulte o seu Painel.

Atenção: Em ambos os casos, por questões de segurança, recomenda-se não expor estes parâmetros no front-end do seu sistema. Sendo assim, as chamadas para os serviços de integração que exigem autenticação devem ser feitos diretamente do back-end.

Geração de Boletos

Esta consulta possibilita a geração de um boleto único ou vários boletos com diferentes vencimentos para cada cliente.

URL: POST https://ws.pagseguro.uol.com.br/recurring-payment/boletos{autenticação}

O serviço retorna o código da transação gerada para cada boleto. Como o processamento é síncrono, os códigos gerados são necessários para consulta individual de cada boleto posteriormente na API de Notificação.

Formato de dados para envio e resposta

Os serviços utilizam o formato JSON quanto com o formato, seja para entrada ou para saída. Além disso, também é possível enviar os dados diretamente na URL da requisição. Para tal, deve-se explicitar no cabeçalho (header) da chamada HTTP os seguintes parâmetros:

Content-type: application/json;charset=ISO-8859-1

Accept: application/json;charset=ISO-8859-1

Atenção: Independentemente do formato de dados utilizado, a codificação de caracteres padrão para a integração é a ISO-8859-1. Tome o cuidado de sempre enviar os dados com este encoding de caracteres. Os dados enviados pelo PagSeguro sempre estarão neste encoding.