Manual do Desenvolvedor

Boleto Bancário

estamos todos ligados

Clique nos hiperlinks para navegar no material do Manual do Desenvolvedor Boleto Bancário.

Boleto Bancário 3

Elementos da solicitação 4

2.1 BoletoTxn 4

2.2 Exemplo de XML 6

Elementos da resposta 7

Elementos para transação query (consulta) 9

4.1 Elementos da solicitação 9

4.2 Elementos da resposta 9

Consolidação dos boletos 12

Códigos de resposta específicos para boleto 13

01

0506

0403

02ÍND

ICE

3

Índice

Manual do Desenvolvedor 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 repassesdos 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.

01 Boleto Bancário

4

Índice

Manual do Desenvolvedor Boleto Bancário

Nome do elemento BoletoTxn

Posição Request.Transaction

02O seguinte elemento complexo pode ser enviado na solicitação XML e será incluído no pedido de autorização da transação.

• Requesto 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

Elementos da solicitação

BoletoTxn

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 clientePor exemplo: Senhor, Senhora, Senhorita

O

first_name Primeiro nome do cliente Alfanumérico O

last_nameO último nome/sobrenome do cliente

Alfanumérico O

5

Índice

Manual do Desenvolvedor Boleto Bancário

Elementos da Solicitação do BoletoTxn

Nome do elemento Descrição Valores/Limitações Obrigatório?

billing_street1O endereço de cobrança (primeira linha)

Alfanumérico O

billing_street2O endereço de cobrança (segunda linha)

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 O

customer_email Endereço de e-mail do cliente64 caracteres no máximo, deve conter @ e.

O

customer_ip O endereço IPv4 do cliente nnn.nnn.nnn.nnn O

instructions

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

interest_per_day

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.

Numérico O

overdue_fineTaxa percentual fixa aplicada caso o boleto seja pago em qualquer data após o vencimento.

Numérico O

processor_id

11 = Itaú12 = Bradesco13 = Banco do Brasil14 = HSBC15 = Santander16 = Caixa

2 dígitos numéricos O

Obs.: a Composição dos campos “first_name” e “last_name” não deve ultrapassar63 caracteres juntos.

6

Índice

Manual do Desenvolvedor Boleto Bancário

Exemplo XML de solicitação para bloco de dados BoletoTxn

Exemplo XML de solicitação boleto

2.2 Exemplo de XML:

<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>null@test.com</customer_email> <last_name>Schmoe</last_name> <billing_street1>12 Abyford Road</billing_street1></BoletoTxn>

<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>null@test.com</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>

7

Índice

Manual do Desenvolvedor Boleto Bancário

Nome do elemento BoletoTxn

Posição Response

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.

03 Elementos da resposta

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 provedorReferência formatada em UUID

transaction_id Referência exclusiva do provedor para esta transaçãoNumérica, máximode 20 dígitos

txn_status Indica se o boleto foi pago Pendente e pago

8

Índice

Manual do Desenvolvedor Boleto Bancário

Elementos de resposta do BoletoTxn

Nome do elemento Descrição Valores / Limitações

txn_fine_value Qualquer multa paga sobre o boletoNumérico, formatado para a moeda

txn_total_due A quantia total devida sobre o boleto, inclusive multasNumérico, formatado para a moeda

txn_paid_value O valor efetivamente pago do boletoNumérico, formatado para a moeda

boleto_barcodeO 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.

Numérico

Exemplo XML de resposta para boleto

<Response version=”2”> <BoletoTxn> <method>payment</method> <language>es</language> <customer_email>john@mail.com</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>

9

Índice

Manual do Desenvolvedor Boleto Bancário

<barcode_number>23791234056000000000401000123404856240000010000</barcode_number> </BoletoTxn> <gateway_reference>4200000027950077</gateway_reference> <merchantreference>boleto1234</merchantreference> <mode>LIVE</mode> <reason>ACCEPTED</reason> <status>1</status> <time>1341312709</time></Response>

• 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

Uma transação query pode ser realizada para uma transação de boleto da mesma forma que uma transação com cartão.

04 Elementos para transação query (consulta)

4.1 Elementos da solicitação

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.

4.2 Elementos da resposta

10

Índice

Manual do Desenvolvedor Boleto Bancário

Exemplo XML de solicitação para bloco de dados BoletoTxn

Exemplo de resposta XML para payment_status = PENDING

<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>

<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=LmO9fsnOXyUgTcRusHkbMQFQxVkk9OBmXEK5CanaeV8JEVxxqROSI7%2Bawb9qrL8ZTSC4pnEbe8iF%0AmHp1r%2FX7Vg%3D%3D</boleto_url> <customer_email>jojojo@dominio.com.br</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>

11

Índice

Manual do Desenvolvedor Boleto Bancário

<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=LmO9fsnOXyUgTcRusHkbMQFQxVkk9OBmXEK5CanaeV%2FHdhcaC70EcHH2dNlwmP53TSC4pnEbe8iF%0AmHp1r%2FX7Vg%3D%3D</boleto_url> <customer_email>jojojo@dominio.com.br</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>

12

Í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>

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.

05 Consolidação dos boletos

13

Índice

Manual do Desenvolvedor Boleto Bancário

Como parte da implementação, os seguintes códigos de resposta “Específicos do Boleto” foram criados.

06 Códigos de resposta específicos para boleto

Código Código de retorno geral Descrição

1911 Payment pendingUma transação válida de “pagamento” foi recebida, mas ainda não houve nenhuma “payment_notification”

1912 Not enabled for Boleto BancarioO 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 elementUm 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

1917Payment notification can only be sent internally

A notificação de pagamento deve ser enviada com credenciais internas

1918Payment notification attempted against non-existent transaction

Nenhuma transação de pagamento do Boleto Bancário correspondente encontrada

1919Payment notification attempted against an already-paid transaction

A transação de pagamento correspondente do Boleto Bancário já foi paga

1920Payment notification attempted with a different vTID

A notificação de pagamento deve utilizar o mesmo vTID que a transação de pagamento do Boleto Bancário