Manual do Desenvolvedor Boleto Bancário estamos todos ligados
ÍNDICE 01 02 03 Boleto Bancário 3 Elementos da solicitação 4 2.1 BoletoTxn 4 2.2 Exemplo de XML 6 Elementos da resposta 7 04 05 06 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 Clique nos hiperlinks para navegar no material do Manual do Desenvolvedor Boleto Bancário.
3 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. 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 - brigatório - pcional X Excluir - Preencher esse campo pode causar a falha da transação bs.: 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.
4 02 Elementos da solicitaçã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 Posição BoletoTxn Request.Transaction Elementos da Solicitação do BoletoTxn Nome do elemento Descrição Valores/Limitações brigató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 language Idioma do cliente Tag de língua do IETF title Título/título honorífico do cliente Por exemplo: Senhor, Senhora, Senhorita first_name Primeiro nome do cliente Alfanumérico last_name último nome/sobrenome do cliente Alfanumérico R
5 Elementos da Solicitação do BoletoTxn Nome do elemento Descrição Valores/Limitações brigatório? billing_street1 billing_street2 endereço de cobrança (primeira linha) endereço de cobrança (segunda linha) Alfanumérico Alfanumérico billing_city A cidade de faturamento Alfanumérico billing_state_ province estado da cobrança do boleto Alfanumérico billing_postcode código postal de cobrança Alfanumérico billing_country país de cobrança Alfanumérico 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. customer_ip endereço IPv4 do cliente nnn.nnn.nnn.nnn instructions interest_per_day overdue_fine processor_id Instruções ao caixa que receber o pagamento do cliente, por exemplo: validar com documento com foto, não aceitar pagamento com cheque. 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 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. Numérico Numérico 2 dígitos numéricos bs.: a Composição dos campos first_name e last_name não deve ultrapassar 63 caracteres juntos.
6 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>null@test.com</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>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 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 Posição BoletoTxn 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 transaction_id ID exclusiva do boleto gerado pelo provedor Referência exclusiva do provedor para esta transação Referência formatada em UUID Numérica, máximo de 20 dígitos txn_status Indica se o boleto foi pago Pendente e pago
8 Elementos de resposta do BoletoTxn Nome do elemento Descrição Valores / Limitações txn_fine_value txn_total_due txn_paid_value boleto_barcode Qualquer multa paga sobre o boleto A quantia total devida sobre o boleto, inclusive multas valor efetivamente pago do boleto 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, 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>john@mail.com</customer_email> <customer_ip>127.0.0.1</customer_ip> <title>mr</title> <first_name>jhn</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 <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.
10 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 m9fsnxyugtcrushkbmqfqxvkk9bmxek5canaev8jevxxqrsi7%2bawb9qrl8z TSC4pnEbe8iF%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 <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=lm9fs nxyugtcrushkbmqfqxvkk9bmxek5canaev%2fhdhcac70echh2dnlwmp53tsc4pne be8if%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 <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. modelo pode ser baixado em nosso portal na Área do Desenvolvedor.
13 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 1912 Not enabled for Boleto Bancario Uma transação válida de pagamento foi recebida, mas ainda não houve nenhuma payment_notification 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 1917 1918 1919 1920 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 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