Manual do Desenvolvedor Boleto Bancário

Transcrição

1 Manual do Desenvolvedor Boleto Bancário Março de 2013 Versão 1.0

2 Índice Página 1. Boleto Bancário Elementos da Solicitação BoletoTxn Exemplo de XML: Elementos da Resposta Elementos para Transação Query (consulta) Elementos da Solicitação Elementos da Resposta Exemplo de XML Códigos de resposta específicos para Boleto... 8

3 1. Boleto Bancário Mais uma das opções de pagamento do e-commerce Redecard é o Boleto bancário. Com ele o estabelecimento tem a opção de gerar os boletos para seus consumidores pela Plataforma. Para usar este serviço o cliente precisa ter contrato com seu banco para receber os créditos. A geração do Boleto é efetuada no e-commerce e os repasses dos valores são diretamente com o Banco. É possível utilizar este tipo de pagamento em conjunto com a funcionalidade HPS e HCC, bem como Fraude e Serviços de Risco. A seguinte legenda será utilizada neste documento: R - brigatório - pcional X Excluir - preencher este campo pode causar a falha da transação 2. 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 da Referência dos Desenvolvedores do e-commerce Redecard BoletoTxn consulte a Seção BoletoTxn Nome do Elemento: Posição: BoletoTxn Request.Transaction Elementos da Solicitação do BoletoTxn Nome do Elemento Descrição Valores/ Limitações 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 brigatório? R

4 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 billing_street1 endereço de cobrança (primeira linha) Alfanumérico billing_street2 endereço de cobrança (segunda linha) Alfanumérico billing_city A cidade de faturamento Alfanumérico billing_state_province estado da cobrança doleto billing_postcode código postal de cobrança Alfanumérico Alfanumérico billing_country país de cobrança Alfanumérico customer_telephone customer_ Número de telefone do portador Endereço de do cliente 64 caracteres no máximo, deve e. customer_ip endereço IPv4 do cliente nnn.nnn.nnn.nnn instructions interest_per_day overdue_fine processorid 11 = Itaú 12 = Bradesco 13 = Banco do Brasil 14 = HSBC 15 = Santander 16 = Caixa 2 dígitos numéricos 2.2 Exemplo de XML: Exemplo XML de Solicitação para bloco de dados BoletoTxn <BoletoTxn> <instructions>here are some instructions</instructions> <expiry_date> </expiry_date> <customer_ip> </customer_ip> <method>payment</method> <first_name>joe</first_name> <customer_ >[email protected]</customer_ > <last_name>schmoe</last_name> <billing_street1>12 Abyford Road</billing_street1> </BoletoTxn>

5 Exemplo XML de Solicitação Boleto <Request version\='2'> <Authentication> <password>************</password> <AcquirerCode> <rdcd_pv> </rdcd_pv> </AcquirerCode> </Authentication> <Transaction> <BoletoTxn> <instructions>here are some instructions</instructions> <expiry_date> </expiry_date> <customer_ip> </customer_ip> <method>payment</method> <first_name>joe</first_name> <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> 3. Elementos da Resposta A resposta do e-commerce Redecard 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 (através de uma transação de consulta). Além dos elementos abordados nesta seção, as respostas para este serviço também contêm os elementos de Resposta gerais, conforme descritos na Seção da Referência dos Desenvolvedores do e-commerce Redecard.Erro! Fonte de referência não encontrada. 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

6 Elementos de Resposta do BoletoTxn Nome do Elemento Descrição Valores / Limitações url order_id transaction_id txn_status txn_fine_value txn_total_due txn_paid_value Qualquer multa paga através do Boleto A quantia total devida sobre o Boleto, inclusive multas pendente pago Exemplo XML de Resposta para Boleto <Response version="2"> <BoletoTxn> <method>payment</method> <language>es</language> <customer_ >[email protected]</customer_ > <customer_ip> </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> </customer_telephone> <interest_per_day>0.1</interest_per_day> <overdue_fine>0.05</overdue_fine> <expiry_date> </expiry_date> <processor_id>11</processor_id> <instructions>não aceitar pagamento em cheques. Inadimplente - Percentual Juros Dia: 10%. Percentual Multa: 5%.</instructions> <url> <order_id>7f000001:013829a1c09e:8de9:016891f0</order_id> <transaction_id> </transaction_id> <txn_status>pending</txn_status> </BoletoTxn> <gateway_reference> </gateway_reference> <merchantreference>boleto1234</merchantreference> <mode>live</mode> <reason>accepted</reason> <status>1</status> <time> </time> </Response>

7 4. 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 da Referência dos Desenvolvedores do e-commerce RedecardErro! Fonte de referência não encontrada. o Transaction HistoricTxn consulte a Seção da Referência dos Desenvolvedores do e-commerce RedecardErro! Fonte de referência não encontrada. 4.2 Elementos da Resposta A resposta do e-commerce Redecard para uma informação de transação de Consulta pode variar, dependendo o 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 maiores detalhes sobre os campos disponíveis Exemplo de XML Exemplo XML de Solicitação para bloco de dados BoletoTxn <Request version="2"> <Authentication> <password>####</password> <AcquirerCode> <rdcd_pv> </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>

8 <billing_postcode> </billing_postcode> <billing_street1>av. Paulista 1111</billing_street1> <boleto_number>536</boleto_number> <boleto_url> ef=lm9fsnxyugtcrushkbmqfqxvkk9bmxek5canaev8jevxxqrsi7%2bawb9qrl8ztsc4 pnebe8if%0amhp1r%2fx7vg%3d%3d</boleto_url> <customer_ip> </customer_ip> <customer_telephone> </customer_telephone> <expiry_date> </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> <overdue_fine>0.01</overdue_fine> <payment_status>pending</payment_status> <processor_id>11</processor_id> <transaction_id>543966</transaction_id> </BoletoTxn> <datacash_reference> </datacash_reference> <merchantreference>teste </merchantreference> <reason>boleto Bancario payment pending</reason> <status>1911</status> </QueryTxnResult> <mode>live</mode> <reason>accepted</reason> <status>1</status> <time> </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> </billing_postcode> <billing_street1>av. Paulista 1111</billing_street1> <boleto_number>175</boleto_number> <boleto_url> ef=lm9fsnxyugtcrushkbmqfqxvkk9bmxek5canaev%2fhdhcac70echh2dnlwmp53tsc4 pnebe8if%0amhp1r%2fx7vg%3d%3d</boleto_url> <customer_ >[email protected]</customer_ > <customer_ip> </customer_ip> <customer_telephone> </customer_telephone> <expected_amount>399</expected_amount> <expiry_date> </expiry_date> <first_name>daniel</first_name>

9 <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>175</order_id> <overdue_fine>0.01</overdue_fine> <paid_amount>350.00</paid_amount> <payment_date> </payment_date> <payment_status>paid</payment_status> <processor_id>11</processor_id> <transaction_id>485821</transaction_id> </BoletoTxn> <datacash_reference> </datacash_reference> <merchantreference>teste110458</merchantreference> <reason>accepted</reason> <status>1</status> </QueryTxnResult> <mode>live</mode> <reason>accepted</reason> <status>1</status> <time> </time> </Response>

10 5. 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 Motivo 1911 Payment pending Descrição 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 Bancario 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 Payment notification can only be sent internally A notificação de pagamento deve ser enviada com credenciais internas 1918 Payment notification attempted against non-existent transaction Nenhuma transação de pagamento do Boleto Bancário correspondente encontrada 1919 Payment notification attempted against an already-paid transaction A transação de pagamento correspondente do Boleto Bancário já foi paga 1920 Payment notification attempted with a different vtid A notificação de pagamento deve utilizar o mesmo vtid que a transação de pagamento do Boleto Bancario