manual do desenvolvedor boleto bancário - userede.com.br · txn_fine_value qualquer multa paga...
TRANSCRIPT
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>[email protected]</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>[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>
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>[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>
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>[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>
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>[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>
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