Manual do Desenvolvedor
Boleto Bancário
estamos todos ligados
ÍNDICE
01
02
03
04
Boleto Bancário3
Elementos da solicitação4
2.1 BoletoTxn4
2.2 Exemplo de XML6
Elementos da resposta7
Elementos para transação
query (consulta) 9
4.1 Elementos da solicitação9
05
06
4.2 Elementos da resposta9
Consolidação dos boletos12
Códigos de resposta
específicos para boleto13
Clique nos hiperlinks para navegar no material
do Manual do Desenvolvedor Boleto Bancário.
Manual do Desenvolvedor Boleto Bancário
01
Boleto Bancário
Mais uma das opções de pagamento do e-Rede é o Boleto Bancário.
Com ele o estabelecimento tem a opção de gerar os boletos
para seus consumidores pela plataforma.
Para usar esse serviço, o cliente precisa ter contrato com seu banco
para receber os créditos.
A geração do boleto é efetuada no e-Rede, e os repasses
dos valores são diretamente com o banco.
É possível reemitir um boleto até três vezes com o mesmo número
de boleto por meio do envio da solicitação XML com o mesmo número
do estabelecimento constante no boleto original.
O número inicial do boleto será automaticamente 1.
Caso você precise usar um número inicial de boleto, isso poderá
ser feito, contanto que indicado no momento da instalação.
A seguinte legenda será utilizada neste documento:
• R - Obrigatório
• O - Opcional
• X – Excluir - Preencher esse campo pode causar
a falha da transação
Obs.: para credenciarmos o Boleto Bancário em nosso sistema e você conseguir
gerar o boleto para os clientes do seu site, é necessário fornecer o código
de contrato que você tem junto ao seu banco pagador dos boletos.
Cada banco pode adotar nomenclaturas distintas para esse número,
por exemplo: número de contrato, número de convênio ou até mesmo cedente.
Verifique com o seu banco esse código e tenha-o à mão para solicitar a geração
dos boletos pelo e-Rede.
Índice
3
4
Manual do Desenvolvedor Boleto Bancário
02
Elementos da solicitação
O seguinte elemento complexo pode ser enviado na solicitação XML
e será incluído no pedido de autorização da transação.
• Request
o Transaction
• TxnDetails – Consulte a seção 2.2.1.3 da referência
dos desenvolvedores do e-Rede
• BoletoTxn – Consulte a seção 2.1
2.1
BoletoTxn
Nome do elemento
BoletoTxn
Posição
Request.Transaction
Elementos da Solicitação do BoletoTxn
Nome do elemento
Descrição
Valores/Limitações
Obrigatório?
method
Tipo de transação
payment
R
expiry_date
Data de validade a ser atribuída
ao Boleto que está sendo emitido.
Pode ser de até 12 meses
no futuro.
AAAA-MM-DD
R
language
Idioma do cliente
Tag de língua do IETF
O
title
Título/título honorífico do cliente
Por exemplo: Senhor,
Senhora, Senhorita
O
first_name
Primeiro nome do cliente
Alfanumérico
O
last_name
O último nome/sobrenome
do cliente
Alfanumérico
O
Índice
5
Manual do Desenvolvedor Boleto Bancário
Elementos da Solicitação do BoletoTxn
Nome do elemento
billing_street1
billing_street2
Descrição
O endereço de cobrança
(primeira linha)
O endereço de cobrança
(segunda linha)
Valores/Limitações
Obrigatório?
Alfanumérico
O
Alfanumérico
O
billing_city
A cidade de faturamento
Alfanumérico
O
billing_state_
province
O estado da cobrança do boleto
Alfanumérico
O
billing_postcode
O código postal de cobrança
Alfanumérico
O
billing_country
O país de cobrança
Alfanumérico
O
customer_telephone
Número de telefone do portador
customer_email
Endereço de e-mail do cliente
64 caracteres no máximo,
deve conter @ e.
O
customer_ip
O endereço IPv4 do cliente
nnn.nnn.nnn.nnn
O
Instruções ao caixa que receber
o pagamento do cliente,
por exemplo: “validar com
documento com foto, não aceitar
pagamento com cheque”.
Campo alfanumérico.
Máximo de 200 caracteres.
Para caracteres com
acento, o caracter e
o acento ocupam
2 espaços.
Por exemplo: Itaú,
ocuparia 5 caracteres.
O
Numérico
O
Numérico
O
2 dígitos numéricos
O
instructions
interest_per_day
overdue_fine
processor_id
Multa percentual diária aplicada
a um boleto, por exemplo: 0,1
representa a cobrança de 10% por
dia após o vencimento do boleto.
Taxa percentual fixa aplicada caso
o boleto seja pago em qualquer
data após o vencimento.
11 = Itaú
12 = Bradesco
13 = Banco do Brasil
14 = HSBC
15 = Santander
16 = Caixa
O
Obs.: a Composição dos campos “first_name” e “last_name” não deve ultrapassar
63 caracteres juntos.
Índice
Manual do Desenvolvedor Boleto Bancário
2.2
Exemplo de XML:
Exemplo XML de solicitação para bloco de dados BoletoTxn
<BoletoTxn>
<instructions>Here are some instructions</instructions>
<expiry_date>2013-04-01</expiry_date>
<customer_ip>192.168.0.1</customer_ip>
<method>payment</method>
<first_name>Joe</first_name>
<customer_email>[email protected]</customer_email>
<last_name>Schmoe</last_name>
<billing_street1>12 Abyford Road</billing_street1>
</BoletoTxn>
Exemplo XML de solicitação boleto
<Request version\=’2’>
<Authentication>
<password>************</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<BoletoTxn>
<instructions>Here are some instructions</instructions>
<expiry_date>2013-04-01</expiry_date>
<customer_ip>192.168.0.1</customer_ip>
<method>payment</method>
<first_name>Joe</first_name>
<customer_email>[email protected]</customer_email>
<last_name>Schmoe</last_name>
<billing_street1>12 Abyford Road</billing_street1>
</BoletoTxn>
<TxnDetails>
<merchantreference>1006e46a5151d623a</merchantreference>
<amount currency=”BRL”>55.44</amount>
</TxnDetails>
</Transaction>
</Request>
Índice
6
7
Manual do Desenvolvedor Boleto Bancário
03
Elementos da resposta
A resposta do e-Rede incluirá um resumo das informações apresentadas
no pedido da transação, como método, linguagem, informações
de clientes e dados específicos do boleto. Também incluirá informações
necessárias pelo comerciante para suportar a emissão do boleto
para o cliente ou reconciliar dados quando o boleto tiver
sido pago (por meio de uma transação de consulta).
Além dos elementos abordados nesta seção, as respostas
para esse serviço também contêm os elementos de resposta gerais,
conforme descritos na seção 2.1 da referência dos desenvolvedores
do e-Rede.
Importante: os elementos só vão aparecer na resposta se a informação
estiver disponível, por exemplo, o txn_paid_value não estará disponível
ou mostrado se o txn_status estiver pendente, ou seja, o boleto ainda
não foi pago.
Nome do elemento
BoletoTxn
Posição
Response
Elementos de resposta do BoletoTxn
Nome do elemento
Descrição
Valores / Limitações
url
A URL usada para acessar o formulário do boleto
URL HTTPS padrão
order_id
ID exclusiva do boleto gerado pelo provedor
transaction_id
Referência exclusiva do provedor para esta transação
txn_status
Indica se o boleto foi pago
Índice
Referência formatada
em UUID
Numérica, máximo
de 20 dígitos
Pendente e pago
8
Manual do Desenvolvedor Boleto Bancário
Elementos de resposta do BoletoTxn
Nome do elemento
Descrição
txn_fine_value
Qualquer multa paga sobre o boleto
txn_total_due
A quantia total devida sobre o boleto, inclusive multas
txn_paid_value
O valor efetivamente pago do boleto
boleto_barcode
O número e código de barras do boleto. Esse número
sempre contém 47 caracteres e não deve conter
quaisquer espaços ou pontos.
Valores / Limitações
Numérico, formatado
para a moeda
Numérico, formatado
para a moeda
Numérico, formatado
para a moeda
Numérico
Exemplo XML de resposta para boleto
<Response version=”2”>
<BoletoTxn>
<method>payment</method>
<language>es</language>
<customer_email>[email protected]</customer_email>
<customer_ip>127.0.0.1</customer_ip>
<title>MR</title>
<first_name>JOHN</first_name>
<last_name>CAIXA</last_name>
<country>BR</country>
<billing_street1>Address Line 1</billing_street1>
<billing_city>JA</billing_city>
<billing_postcode>12345</billing_postcode>
<billing_country>BR</billing_country>
<customer_telephone>00000000000</customer_telephone>
<interest_per_day>0.1</interest_per_day>
<overdue_fine>0.05</overdue_fine>
<expiry_date>2013-04-01</expiry_date>
<processor_id>11</processor_id>
<instructions>Não aceitar pagamento em cheques. Inadimplente Percentual Juros Dia: 10%. Percentual Multa: 5%.</instructions>
<url>http://www.domain.com/generatedurl456</url>
<order_id>7F000001:013829A1C09E:8DE9:016891F0</order_id>
<transaction_id>1418605</transaction_id>
<txn_status>PENDING</txn_status>
Índice
Manual do Desenvolvedor Boleto Bancário
9
<barcode_number>23791234056000000000401000123404856240000010000</ba
rcode_number>
</BoletoTxn>
<gateway_reference>4200000027950077</gateway_reference>
<merchantreference>boleto1234</merchantreference>
<mode>LIVE</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1341312709</time>
</Response>
04
Elementos para transação query (consulta)
Uma transação query pode ser realizada para uma transação de boleto
da mesma forma que uma transação com cartão.
4.1
Elementos da solicitação
• Request
o Authentication – Consulte a seção 2.1.1.1.1 da referência
dos desenvolvedores do e-Rede
o Transaction
• HistoricTxn – Consulte a seção 2.2.1.4 da referência
dos desenvolvedores do e-Rede
4.2
Elementos da resposta
A resposta do e-Rede para uma informação de transação de consulta
pode variar, dependendo do status de pagamento do boleto.
Por exemplo, se o boleto tiver sido pago, o valor em txn_status será
exibido como paid, e os campos detalhados abaixo irão fornecer
informações adicionais sobre o pagamento. Por favor, consulte a seção 3
para mais detalhes sobre os campos disponíveis.
Índice
Manual do Desenvolvedor Boleto Bancário
Exemplo XML de solicitação para bloco de dados BoletoTxn
<Request version=”2”>
<Authentication>
<password>####</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<HistoricTxn>
<method>query</method>
<reference type=”merchant”>boleto1234</reference>
</HistoricTxn>
</Transaction>
</Request>
Exemplo de resposta XML para payment_status = PENDING
<Response version=’2’>
<QueryTxnResult>
<BoletoTxn>
<amount>100.00</amount>
<billing_city>SP</billing_city>
<billing_country>BR</billing_country>
<billing_postcode>12949-110</billing_postcode>
<billing_street1>Av. Paulista 1111</billing_street1>
<boleto_number>536</boleto_number>
<boleto_url>https://testboletos.maxipago.net/redirection_service/boleto?ref=L
mO9fsnOXyUgTcRusHkbMQFQxVkk9OBmXEK5CanaeV8JEVxxqROSI7%2Bawb9qrL8Z
TSC4pnEbe8iF%0AmHp1r%2FX7Vg%3D%3D</boleto_url>
<customer_email>[email protected]</customer_email>
<customer_ip>127.0.0.1</customer_ip>
<customer_telephone>1135938203</customer_telephone>
<expiry_date>2013-04-01</expiry_date>
<first_name>Daniel</first_name>
<instructions>Não aceitar pagamento em cheques. Percentual Juros
Dia: 1%. Percentual Multa: 1%.</instructions>
<interest_per_day>0.01</interest_per_day>
<last_name>Lucats</last_name>
<merchant_id>3701</merchant_id>
<order_id>536</order_id>
Índice
10
Manual do Desenvolvedor Boleto Bancário
11
<overdue_fine>0.01</overdue_fine>
<payment_status>PENDING</payment_status>
<processor_id>11</processor_id>
<transaction_id>543966</transaction_id>
</BoletoTxn>
<gateway_reference>3600900010035659</gateway_reference>
<merchantreference>Teste28061003</merchantreference>
<reason>Boleto Bancario payment pending</reason>
<status>1911</status>
</QueryTxnResult>
<mode>LIVE</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1372424737</time>
</Response>
Exemplo de Resposta XML para txn_payment = PAID
<?xml version=”1.0” encoding=”UTF-8”?>
<Response version=’2’>
<QueryTxnResult>
<BoletoTxn>
<amount>350.00</amount>
<billing_city>SP</billing_city>
<billing_country>BR</billing_country>
<billing_postcode>12949-110</billing_postcode>
<billing_street1>Av. Paulista 1111</billing_street1>
<boleto_number>175</boleto_number>
<boleto_url>https://testboletos.maxipago.net/redirection_service/boleto?ref=LmO9fs
nOXyUgTcRusHkbMQFQxVkk9OBmXEK5CanaeV%2FHdhcaC70EcHH2dNlwmP53TSC4pnE
be8iF%0AmHp1r%2FX7Vg%3D%3D</boleto_url>
<customer_email>[email protected]</customer_email>
<customer_ip>127.0.0.1</customer_ip>
<customer_telephone>1135938203</customer_telephone>
<expected_amount>399</expected_amount>
<expiry_date>2013-04-01</expiry_date>
<first_name>Daniel</first_name>
<instructions>Não aceitar pagamento em cheques. Percentual Juros Dia: 1%.
Percentual Multa: 1%.</instructions>
<interest_per_day>0.01</interest_per_day>
<last_name>Lucats</last_name>
Índice
Manual do Desenvolvedor Boleto Bancário
<merchant_id>3701</merchant_id>
<order_id>175</order_id>
<overdue_fine>0.01</overdue_fine>
<paid_amount>350.00</paid_amount>
<payment_date>2013-04-14</payment_date>
<payment_status>PAID</payment_status>
<processor_id>11</processor_id>
<transaction_id>485821</transaction_id>
</BoletoTxn>
<gateway_reference>3900900010002228</gateway_reference>
<merchantreference>Teste110458</merchantreference>
<reason>ACCEPTED</reason>
<status>1</status>
</QueryTxnResult>
<mode>LIVE</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1372425377</time>
</Response>
05
Consolidação dos boletos
Para efetuar a consolidação dos boletos bancários gerados no e-Rede,
precisamos receber o arquivo bancário com os dados de boletos pagos
e ainda pendentes para disponibilização no nosso portal.
Para isso seu banco deve ser autorizado por você para nos enviar o arquivo.
Utilize a carta padrão para essa autorização.
O modelo pode ser baixado em nosso portal na Área do Desenvolvedor.
Índice
12
13
Manual do Desenvolvedor Boleto Bancário
06
Códigos de resposta
específicos para boleto
Como parte da implementação, os seguintes códigos de resposta
“Específicos do Boleto” foram criados.
Código
Código de retorno geral
Descrição
1911
Payment pending
Uma transação válida de “pagamento” foi recebida,
mas ainda não houve nenhuma “payment_notification”
1912
Not enabled for Boleto Bancario
O estabelecimento comercial não pode utilizar
o serviço Boleto Bancário
1913
Invalid value supplied
Um campo contém um valor inválido
1914
Missing mandatory element
Um ou mais elementos obrigatórios (vencimento, etc.)
não foi fornecido
1915
Failure response received
Falha na transação
1916
Communications Error
Erro de comunicação
Payment notification can only be
sent internally
Payment notification attempted
against non-existent transaction
Payment notification attempted
against an already-paid
transaction
Payment notification attempted
with a different vTID
A notificação de pagamento deve ser enviada
com credenciais internas
Nenhuma transação de pagamento do Boleto Bancário
correspondente encontrada
1917
1918
1919
1920
Índice
A transação de pagamento correspondente do Boleto
Bancário já foi paga
A notificação de pagamento deve utilizar o mesmo
vTID que a transação de pagamento do Boleto Bancário