Aprova Fácil Integração via WebService Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 1 Prezado Cliente, Este é o Manual de integração do Aprova Fácil – Modo WebService, que deve ser encaminhado ao seu desenvolvedor. O modo WebService é uma forma de integração simples, que dispensa a instalação de clientes do Aprova Fácil no servidor do Lojista. Esperamos através desta documentação orientálo da melhor forma possível e aproveitamos a oportunidade para colocarnos à sua disposição para maiores esclarecimentos. Para entrar em contato conosco, utilize os canais de contato disponibilizados na URL abaixo: http://www.cobrebem.com/contato.html Nota: De acordo com as exigências do PCIDSS a Cobre Bem Tecnologia não é autorizada a receber números de cartão de crédito. Caso necessite de suporte em relação a alguma transação efetuada, nos informe o número da transação. Boas cobranças e Cobre Bem! Equipe Cobre Bem Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 2 ÍNDICE 1. Introdução..........................................................................................................................................................................6 2. Integração...........................................................................................................................................................................7 2.1. Meios de Pagamento Suportados................................................................................................................................7 2.2. Tecnologias de Conectividade....................................................................................................................................7 2.3. Etapas da Automatização............................................................................................................................................8 2.4. Tempo de Captura de uma Transação Aprovada........................................................................................................8 2.5. Codificação da Resposta do Aprova Fácil................................................................................................................10 3. Cartão de Crédito – Pedido de Aprovação – APC.......................................................................................................11 3.1. Descrição...................................................................................................................................................................11 3.2. Métodos de Envio......................................................................................................................................................11 3.3. URLs Chamada........................................................................................................................................................11 3.4. Parâmetros do Pedido................................................................................................................................................12 3.5. Agendamento Descrição.........................................................................................................................................15 3.6. Recorrência – Descrição............................................................................................................................................16 3.7. Consulta AVS (Adress Verification Service)...........................................................................................................18 3.8. Exemplo de Pedido ...................................................................................................................................................19 3.9. Resultado do Processamento Formato XML............................................................................................................21 3.10. Resultados de Erros Comuns..................................................................................................................................24 4. Cartão de Crédito – Pedido de Captura – CAP ..........................................................................................................26 4.1. Descrição...................................................................................................................................................................26 4.2. CAP – Métodos de Envio..........................................................................................................................................26 4.3. URLs..........................................................................................................................................................................26 4.4. Parâmetros de Requisição.........................................................................................................................................27 4.5. Exemplos de Requisição GET..................................................................................................................................27 4.6. Exemplo de Resultados.............................................................................................................................................28 4.7. Resultado de Captura com Sucesso..........................................................................................................................28 4.8. Resultados de Erro Comuns......................................................................................................................................28 5. Cartão de Crédito – Cancelamento de Transações – CAN.........................................................................................30 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 3 5.1. Descrição...................................................................................................................................................................30 5.2. Métodos de Envio......................................................................................................................................................30 5.3. URLs..........................................................................................................................................................................30 5.4. Parâmetros de Requisição.........................................................................................................................................31 5.5. Exemplos de Requisição...........................................................................................................................................31 5.6. Resultado XML.........................................................................................................................................................32 5.7. Resultado das Tags XML..........................................................................................................................................32 5.8. Exemplos de Resultados............................................................................................................................................32 5.9. Resultado de Cancelamento com Sucesso................................................................................................................34 5.10. Resultados de Erros Comuns NSU Cancelamento.................................................................................................34 6. Cartão de Crédito – Call Back de Reembolso..............................................................................................................35 6.1. Descrição...................................................................................................................................................................35 6.2. Métodos de Envio......................................................................................................................................................35 6.3. URLs..........................................................................................................................................................................35 6.4. Parâmetros de Requisição.........................................................................................................................................35 6.5. Resposta a uma Solicitação de Reembolso Bem Sucedida......................................................................................36 7.Cartão de Crédito – Resultado de Reembolso...............................................................................................................37 7.1. Descrição...................................................................................................................................................................37 7.2. Métodos de Envio......................................................................................................................................................37 7.3. Envio do Resultado de Reembolso...........................................................................................................................37 7.4. Exemplo de chamada................................................................................................................................................37 7.5. Descrição dos parâmetros..........................................................................................................................................38 7.6. Confirmação de Recebimento de Retorno................................................................................................................38 8. Boleto Bancário – Pedido de Emissão – BOL...............................................................................................................39 8.1. Descrição...................................................................................................................................................................39 8.2. Métodos de Envio......................................................................................................................................................39 8.3. URL's.........................................................................................................................................................................39 8.4. Parâmetros de Requisição.........................................................................................................................................39 8.5. Exemplo de Requisição ............................................................................................................................................41 8.6. Resultados..................................................................................................................................................................41 8.7.Resultados de Erros Comuns.....................................................................................................................................42 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 4 9. Transferências Bancárias On Line – Pedido de Aprovação........................................................................................43 9.1. Descrição...................................................................................................................................................................43 9.2. Métodos de Envio......................................................................................................................................................43 9.3. URLs..........................................................................................................................................................................43 9.4. Parâmetros de Requisição.........................................................................................................................................43 9.5. Requisição.................................................................................................................................................................44 9.6. Exemplo de Resultados.............................................................................................................................................44 9.7. Resultados de Erros Comuns....................................................................................................................................47 10. Transferências Bancárias On Line – Retorno de Confirmação de Pedido..............................................................48 10.1. Descrição.................................................................................................................................................................48 10.2. Métodos de Envio....................................................................................................................................................48 10.3. URL.........................................................................................................................................................................48 10.4. Parâmetros de Retorno............................................................................................................................................48 10.5. Exemplo de Retorno................................................................................................................................................50 10.6. Resultados de Erros Comuns..................................................................................................................................50 11. Débito Automático em Conta Corrente – Pedido de Aprovação – DEB.................................................................51 11.1. Descrição.................................................................................................................................................................51 11.2. Métodos de Envio....................................................................................................................................................51 11.3. URL.........................................................................................................................................................................51 11.4. Parâmetros de Requisição.......................................................................................................................................51 11.5. Exemplo de Requisição...........................................................................................................................................53 11.6. Exemplo de Resultados...........................................................................................................................................54 12. Diagrama de Funcionamento.......................................................................................................................................55 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 5 1. Introdução O WebService é uma das formas disponíveis para efetuar a integração de sua loja virtual/aplicativo com a solução de automatização de vendas através de diversos meios de pagamento, o gateway Aprova Fácil. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 6 2. Integração Para iniciar este processo, o desenvolvedor deve nos informar o endereço de IP fixo do estabelecimento que estará usando o Gateway de Pagamentos Aprova Fácil. É obrigatório que o endereço de IP seja fixo para este método de integração. Se o endereço IP do comerciante não for fixo, o método de integração ideal é o STAC, em que o comprador é redirecionado para o ambiente seguro da Cobre Bem Tecnologia, onde todos os dados sensíveis serão inseridos. Por favor, solicite o manual de integração STAC se este estiver mais adequado à sua situação. Nota : Quando o ambiente de testes da Cobre Bem estiver sendo usado , não é necessário informar um endereço de IP, porque o nosso servidor de teste não valida o IP de origem da transação. 2.1. Meios de Pagamento Suportados O Aprova Fácil realiza a automatização de diversos meios de pagamento simultaneamente com Bancos e Administradoras de Cartões de Crédito, utilizando a internet como meio de captura. http://www.cobrebem.com/aprovafacil.html 2.2. Tecnologias de Conectividade Integração WebService é suportado apenas por conectividades tecnologia 2D. Esse tipo de tecnologia não redireciona o cliente para o site do adquirente, a fim de preencher as informações do cartão. Por favor, veja abaixo: TEF Buy Page Loja Komerci Web Service Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 7 2.3. Etapas da Automatização 2.3.1. Cartão de Crédito a) Requisição de aprovação; b) Requisição de captura; c) Requisição de cancelamento; d) Cancelamento de retorno nãoimediato (Reembolso); 2.3.2. Boleto Bancário a) Pedido de emissão; b) Lista de confirmação de pagamento. 2.3.3. Transferência Bancária On line (Débito On Line) a) Requisição de aprovação; b) Confirmação de recebimento de resultado; c) Retorno de confirmação de pagamento. 2.3.4. Débito em Conta Corrente a) Pedido de aprovação; b) Solicitação de Resultado de Transação. 2.4. Tempo de Captura de uma Transação Aprovada Nas vendas realizadas através do meio de pagamento Cartão de Crédito, é possível realizar confirmação (captura) da transação de 02 (duas) formas: – Manual; – Automática. A confirmação/captura de uma transação se refere ao envio para a Administradora da confirmação do pedido por parte da loja. A reserva de crédito estabelecida na aprovação é transformada em um débito efetivo no cartão de crédito do Cliente. A confirmação/captura pode ser realizada de forma Manual ou Automática, Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 8 dependendo da implementação realizada pelo desenvolvedor. O Lojista determina o modo da confirmação/captura de acordo com o tipo de venda/negócio adotado. Geralmente, o Lojista adota o modo de confirmação com captura manual, quando deseja realizar uma verificação do pedido antes de confirmar/capturar a transação junto à Administradora de Cartão de Crédito. Caso o lojista não realize a captura da transação no prazo estipulado pelas Administradoras de Cartão de Crédito, de acordo com a tecnologia de conectividade, a mesma será desfeita automaticamente. Nesse caso, o débito não será realizado no cartão de crédito do cliente. O lojista poderá visualizar a data/hora desse processo, denominado “Desfazimento” da transação, no campo “Data/Hora Cancelamento” existente no Extrato do Aprova Fácil. Segue um quadro ilustrativo, contendo os prazos de confirmação (captura) da transação, de acordo com a tecnologia de conectividade e Administradora de Cartão de Crédito para sua análise. Acquirer Cielo Connectivity Technology Brand Confirmation Deadline Buy Page Loja (2D) Diners / MasterCard / Visa / Amex Até 5 dias Buy Page Cielo (3D) Diners / MasterCard / Visa / Amex Até 5 dias Komerci (3D) Diners / MasterCard / Visa / Hipercard 2 minutos 5 minutos Rede Komerci WebService (2D) Diners / MasterCard / Visa Somente é possível captura Manual com Pré Autorização, neste caso são 5 dias. (*) veja Nota 1 47 horas por padrão, mas Santander GetNet TEF (2D) MasterCard / Visa pode ser prorrogado até 20 dias, enviar email para [email protected] Elavon TEF (2D) Diners / MasterCard / Visa Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 47 horas 9 Sorocred TEF (2D) Sorocred 47 horas Cetelem TEF (2D) Aura 47 horas As tecnologias de conectividade Komerci e Komerci WebService da Adquirente REDE não permitem confirmação (captura) do tipo manual, somente a automática com prazo de confirmação (captura) máxima de 2 e 5 minutos, respectivamente. Nota 1: Caso o estabelecimento esteja habilitado na tecnologia de conectividade Komerci WebService com “PréAutorização”, junto à Adquirente REDE, a captura poderá ser realizada de forma manual. Neste caso, o prazo para realizar a confirmação (captura) é de 5 dias corridos a partir da data do processamento realizado pela Adquirente de Cartão de Crédito REDE. 2.5. Codificação da Resposta do Aprova Fácil Se desejar que a resposta seja codificada em UTF8, utilize na requisição, o parâmetro ResponderEmUTF8 passando para ele o valor “S”. Caso contrário, a resposta será em ISO 88591. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 10 3. Cartão de Crédito – Pedido de Aprovação – APC 3.1. Descrição O pedido de aprovação deverá ser usado sempre que a aplicação do desenvolvedor precisar da aprovação financeira para uma venda com cartão de crédito. Existem três tipos de pedidos de aprovação: venda única, venda recorrente e venda agendada. O pedido de venda única ocorre quando os dados são enviados ao Aprova Fácil, que, por sua vez, os envia para a Administradora, esta retorna com a resposta de aprovação ou não aprovação da transação. O pedido de venda recorrente ocorre quando um ID de pedido previamente processado é enviado ao Aprova Fácil, ao invés da informação do cartão de crédito. Assim, o Aprova Fácil recupera as informações da transação prévia do cartão de crédito e as inclui nos parâmetros recebidos antes de processála. O pedido de venda agendada ocorre quando há a necessidade de efetuar débito mensal no cartão de crédito. O Aprova Fácil realiza as transações de forma automática a partir da primeira transação aprovada no agendamento, criado de acordo com a quantidade de meses estipulada. 3.2. Métodos de Envio Como os dados passados no envio do pedido são sigilosos, o método de envio a ser adotado é o POST, através de HTTPS. 3.3. URLs Chamada 3.3.1. Servidor principal: Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 11 3.3.2. Servidor de teste: Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 3.4. Parâmetros do Pedido Nota: Se não quiser usar um parâmetro opcional, simplesmente deixeo em branco. Tecnologias: TEF / Buy Page Loja / Komerci Web Service Nome NumeroDocumento ValorDocumento ValorEntrada* QuantidadeParcelas NumeroCartao MesValidade AnoValidade Descrição Formatação Identificação da venda Exemplo Até 50 caracteres alfanuméricos. 123ABC pela loja. Numérico, sendo as casas Valor da transação decimais separadas por ponto (.) Valor da taxa de Numérico, sendo as casas Obrigatório Não 123.56 Sim 123.56 Não embarque. decimais separadas por ponto (.) Quantidade de parcelas 02 dígitos numéricos 01 Sim Até 19 dígitos numéricos 4551870000000183 Sim 02 dígitos numéricos 11 Sim 02 dígitos numéricos 08 Sim Número do cartão de crédito Mês em que o cartão expira Ano em que o cartão expira Sim, se tecnologia CodigoSeguranca** CVC2/CVV2 do cartão Até 04 dígitos numéricos 123 diferente de Komerci Web Service*** Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 12 Nome PreAutorizacao Descrição Veja Formatação descrição abaixo**** EnderecoIPComprador IP de quem compra NomePortadorCartao Nome que está gravado no cartão Exemplo Obrigatório Char. S=Sim e N= Não S Não 000.000.000.000 200.200.200.0 Sim Até 50 caracteres alfanuméricos José da Silva Não VISA MASTERCARD DINERS Bandeira Bandeira do cartão de AMEX crédito HIPERCARD MASTERCARD Não JCB SOROCRED AURA Adquirente ***** CPFPortadorCartao BT BANORTE CB CREDIBANCO CE CIELO CL CETELEM ELAVON para a transação RA AMEX RC REDE RM REDEBAN SC SOROCRED SM GETNET TB TRANSBANK 14 dígitos numéricos 12345678123412 11 dígitos numéricos 12345678912 aaaammdd 20071027 Não Apenas um caracter: S S Não CPF do portador do cartão portador do cartão ParcelamentoAdministr Utilizado para acionar o adora BANCOMER Adquirentes preferidos PA DataNascimentoPortad Data de nascimento do orCartao BC parcelamento adquirente Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ Não Não 13 Nome Descrição Formatação Exemplo Obrigatório Moeda utilizada na venda Valores válidos: BRL, MXN, (caso não seja informado, CLP (Demais valores ISO para Moeda será assumido o valor definições de moeda ISO BRL) 4217) BRL Não * Deve ser utilizado apenas por companhias aéreas. O uso deste parâmetro necessita ser habilitado pela Cobre Bem Tecnologia. ** É possível controlar o resultado no ambiente de testes do Aprova Fácil. Para isto, utilize o parâmetro “CodigoSeguranca”. Veja abaixo o resultado esperado. Essa modalidade não está disponível para Aura e Sorocred. CodigoSeguranca Informado Retorno 555 ou 123 Autorizado 501 05 05NAO AUTORIZADA 502 78 78CAR BLOQ1.USO 503 41 41 RETER CARTAO 504 14 14CARTAOINVALIDO 506 60 Valor Inválido. Por favor, ent 507 68 T68TRANSACAO JA EFETUADA 508 54 54CARTAO VENCIDO 509 56 Dado Inválido. Por favor, entr 444 N7 N7COD.SEG.INVAL 333 84 T84REFACA TRANS *** Por determinação da Rede o CVV2 não deve ser solicitado do comprador quando a tecnologia utilizada for Komerci Web Service. **** A Préautorização é o bloqueio temporário de uma quantia no cartão de crédito, com objetivo de garantir a sua reserva; é um recurso que pode ser utilizado na tecnologia de conectividade Komerci WebService (REDE). O tipo de venda que contém esse recurso somente é utilizado em projetos especiais que tenham essa necessidade. ***** Reservado para uso futuro (RFU). Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 14 3.5. Agendamento Descrição O agendamento de transações é utilizado, quando há a necessidade de efetuar mensalmente o débito no cartão de crédito do cliente mantendo sempre as mesmas condições: – Mesmo valor; – Débito mensal realizado sempre no mesmo dia. O agendamento é realizado de forma automática pelo Aprova Fácil, obedecendo as regras de débito informadas através dos parâmetros de agendamentos descritos no item 3.5.2 deste manual. Importante: Para que o agendamento seja aceito é necessário que a primeira transação tenha sido aprovada pela Administradora de Cartão de Crédito. Caso contrário, não será realizado o agendamento. 3.5.1. Agendamento – Tecnologia de Conectividade O agendamento é suportado pelas tecnologias de conectividade listadas abaixo: – TEF , Buy Page Loja (Cielo), Komerci WebService (Rede). 3.5.2. Agendamento Parâmetros Utilizados para Agendar uma Transação Os parâmetros de requisição, exibidos na tabela abaixo, devem ser enviados na primeira solicitação de débito do cartão de crédito juntamente com os demais dados do pedido. Neste caso o parâmetro NumeroDocumento passa a ser obrigatório, não poderá ser nulo e deverá ser único. Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 15 Nome Descrição Formatação Utilizado Incluir ou Caracter: I – Incluir Agendamento* Excluir Exemplo I Obrigatório Sim / E – Excluir/ A – Atualizar Transacao Número da Transação de 14 Origem do Agendamento caracteres 7871287987112 Se numéricos 1 Agendamento= A ou E DiaParaAgendar Dia que será feito o débito dd 09 Se Agendamento= I QuantidadeMesesParaAgendar Quantidade de meses a 2 dígitos numéricos 08 debitar Se Agendamento= I NumeroTentativasNaoAprovado Tentativas para 2 dígitos numéricos 04 aprovação Se Agendamento= I QuantidadeDiasEntreTentativas Dias entre cada tentativa 2 dígitos numéricos 03 Se Agendamento= I ParcelamentoAdministradora Utilizado para acionar o Apenas um parcelamento S Não caracter: S administradora * Se o valor A ou E for informado para o parâmetro Agendamento, então tornase obrigatória a utilização do parâmetro Transacao. 3.6. Recorrência – Descrição A recorrência de transações é utilizada, quando se deseja efetuar novos débitos em um cartão de crédito, seja esta de qualquer periodicidade; é possível alterar o valor do débito a cada cobrança, se necessário. O processo de "recobrança" em uma recorrência, se difere do processo de "recobrança" em um agendamento. A recobrança em uma recorrência é comandada pela aplicação do lojista. Nestes casos devem ser Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 16 informados apenas os parâmetros de requisição de recorrência, conforme item 3.6.2 Recorrência – Parâmetros de Requisição. Nota: ID da transação é determinado automaticamente pelo Aprova Fácil, e cada número é único. 3.6.1. Recorrência – Tecnologias de Conectividade A recorrência de transações é suportada pelas tecnologias de conectividade: TEF, Buy Page Loja (Cielo), Komerci WebService (Rede). Existem 3 formas de capturar o CVV2 para Adquirente de Cartão de Crédito Cielo (digitada, chip e trilha). Para trabalhar com recorrência utilizando a tecnologia de conectividade TEF 4.1, é necessário desabilitar a opção digitada de CVV2. 3.6.2. Recorrência – Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Nome Descrição TransacaoAnterior Número da Transação ValorDocumento Valor da transação QuantidadeParcelas Quantidade de parcelas Formatação 14 caracteres numéricos Exemplo 78712879871121 Sim Numérico, sendo as casas decimais separadas por ponto (.) 02 dígitos numéricos ParcelamentoAdmi Utilizado para acionar o Apenas um caracter: S nistradora Obrigatório 123.56 Sim 1 Sim S Não parcelamento administradora Nota: O Número da Transação é criado automaticamente pelo Aprova Fácil, com objetivo de identificar cada transação. Esse número é único e jamais será repetido. Recomendamos que o número da última transação aprovada (referente ao cartão que será recobrado) seja informado no parâmetro “TransacaoAnterior”. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 17 3.7. Consulta AVS (Adress Verification Service) O AVS é um serviço oferecido pelas Administradoras de Cartão de Crédito, para que o lojista possa realizar uma consulta para confirmação dos dados de CPF (Cadastro Pessoa Física) e do endereço de entrega da fatura do titular do cartão no ato da compra . Para disponibilizar essa consulta, o estabelecimento deverá habilitar esse serviço junto às Administradoras de Cartão de Crédito, e, após, informar à Cobre Bem Tecnologia que a mesma será utilizada. A consulta AVS é suportada para a bandeira Mastercard, nas tecnologias de conectividade , Komerci e Komerci WebService, respectivamente. Se o estabelecimento do lojista possuir habilitação para realizar vendas com AVS, no momento da solicitação dos dados, deverão ser informados também os parâmetros de requisição a seguir: Nota: Se você não quiser usar um parâmetro opcional, simplesmente deixálo em branco. Tecnologia Komerci Nome AVS Descrição Valores: N – Não realizar S – Para realizar consulta Formatação Exemplo 01 caracter S Obrigatório Sim, caso deseja que a transação contemple consulta AVS Demais Tecnologias Nome Descrição Formatação Exemplo Obrigatório Valores: N – Não realizar AVS CPFPortadorCartao S – Para realizar consulta 01 caracter maiúsculo S CPF do Portador do cartão 14 dígitos numéricos 12345678123412 de crédito 12345678912 11 dígitos numéricos Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ Sim Se AVS = S 18 Nome Descrição EnderecoPortadorCartao CEPPortadorCartao Formatação Endereço do Portador do Até 50 caracteres cartão de crédito Endereço + número CEP do Portador do cartão de crédito 08 dígitos numéricos Exemplo Obrigatório Av. das flores 123 Se AVS = S 20555000 Se AVS = S 3.8. Exemplo de Pedido 3.8.1. Venda Única Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 3.8.2. Pagamento Recorrente Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 19 3.8.3. Pagamento Agendado Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 3.8.4. Pagamento com Consulta AVS Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 20 Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 3.9. Resultado do Processamento Formato XML Resposta XML do processamento de uma transação. <ResultadoAPC> <TransacaoAprovada>TRUE</TransacaoAprovada> <ResultadoSolicitacaoAprovacao>00 APROVADA</ResultadoSolicitacaoAprovacao> <CodigoAutorizacao>082030</CodigoAutorizacao> <Transacao>73314072604262</Transacao> <CartaoMascarado>455187******0183</CartaoMascarado> <NumeroDocumento>12345</NumeroDocumento> <ComprovanteAdministradora>RETORNO, DEPENDE DA TECNOLOGIA </ComprovanteAdministradora> <NacionalidadeEmissor> </NacionalidadeEmissor> <ResultadoAVS> </ResultadoAVS> <EnderecoAVS> <Endereco> </Endereco> <Numero> </Numero> <Complemento> </Complemento> <Cep> </Cep> </EnderecoAVS> </ResultadoAPC> 3.9.1. Descrição dos Parâmetros Seguem abaixo a descrição e formato dos parâmetros retornados no XML Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 21 Nome TransacaoAprovada Descrição Formatação Resultado do pedido de True = Aprovado aprovação Obrigatório True Sim veja tabela abaixo sim False = Negado ResultadoSolicitacaoAprovac Descrição da aprovação do Texto varchar ao resultado do pedido CodigoAutorizacao Código de autorização Texto de 6 dígitos retornado Exemplo N12345 pela Sim se aprovado Administradora do cartão de crédito Transacao ID da transação Aprova Texto de 14 dígitos 73263868827369 Sim Fácil CartaoMascarado Número mascarado do Até 19 dígitos 444433******111 Sim Cartão de Crédito numéricos 1 NumeroDocumento ID do pedido da companhia Até 50 caracteres 123ABC Sim Adquirente Adquirente usado para a BC BANCOMER Não transação BT BANORTE CB CREDIBANCO CE CIELO CL CETELEM PA ELAVON RA AMEX RC REDE RM REDEBAN SC SOROCRED SM GETNET TB TRANSBANK 6 dígitos numéricos 123456 Não Texto varchar N/A Não Texto nulo N/A Não NumeroSequencialUnico Número de aprovação da Administradora ComprovanteAdministradora Texto comprovante da Administradora NacionalidadeEmissor País emissor Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 22 Nome ResultadoAVS Descrição Formatação Resultado da verificação de Texto nulo Exemplo Obrigatório N/A Não N/A Não endereço (Veja a tabela do item 3.9.2) EnderecoAVS Tag de grupo para endereço N/A verificado Endereco Endereço de rua verificado Texto nulo Numero Número de endereço Texto nulo Não N/A Não N/A Não N/A Não verificado Complemento Complemento do endereço Texto nulo verificado Cep CEP do endereço verificado Texto nulo 3.9.2. Tabela de Valores retornados para o parâmetro ResultadoAVS AMEX Código Descrição X Endereço e CEP 9 dígitos coincidem. Y Endereço e CEP 5 dígitos coincidem. W Somente o CEP 9 dígitos coincide. S Serviço não suportado. G Emissor não participa do AVS. A Endereço coincide. Cep não coincide ou não verificado. Z Cep 5 dígitos coincide. Endereço não coincide. R Emissor não disponível. U Endereço indisponível. N Nada coincide. E Endereço e Cep não informado. REDE Código Descrição W Sim, todos os dígitos coincidem. X O CEP e CPF coincidem, endereço não coincide. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 23 REDE Código Descrição Z Endereço e CPF coincidem, CEP não coincide. Y O CEP coincide, CPF e endereço não coincidem. A CPF coincide, CEP e endereço não coincidem. U O CEP e CPF não coincidem, endereço coincide. S O CEP e endereço coincidem, CPF não coincide. N Nada coincide. 3.10. Resultados de Erros Comuns Texto do Resultado Descrição Erro Valor Inválido Valor Inválido Erro Valor deve ser maior que zero Valor deve ser maior que zero Erro Número Parcelas Inválido Número Parcelas Inválido Erro Número Parcelas deve ser maior que zero Número Parcelas deve ser maior que zero Erro Transação Anterior não Localizada Transação Anterior não Localizada Erro Conectividade não permite recorrência Conectividade não permite recorrência Erro Cartão Inválido Cartão Inválido Erro Estabelecimento não cadastrado para a Bandeira XXX Lojista não pode aceitar XXX pagamentos Adquirinte YYY Erro Estabelecimento não habilitado para a Bandeira XXX XXX desabilitado para o Lojista Adquirinte YYY Erro Código do Emissor do cartão Inválido Código do Emissor do cartão Inválido Erro Mês/Ano Validade Inválidos Mês/Ano Validade Inválidos Erro Cartão fora do prazo de validade Cartão fora do prazo de validade Erro Número Parcelas Agendamento Inválido Número Parcelas Agendamento Inválido Erro Número Parcelas Agendamento deve ser maior que 1 Número Parcelas Agendamento deve ser maior que 1 Erro Dia Débito Inválido Dia Débito Inválido Erro Dia Débito deve estar entre 1 e 31 Dia Débito deve estar entre 1 e 31 Erro Número Tentativas Inválido Número Tentativas Inválido Erro Número Tentativas ser maior que 1 ou igual a zero Número Tentativas ser maior que 1 ou igual a zero Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 24 Texto do Resultado Descrição Erro Dias entre Tentativas Inválido Dias entre Tentativas Inválido Erro Dias entre Tentativas ser maior ou igual a 1 Dias entre Tentativas ser maior ou igual a 1 Erro Cliente sem Estabelecimento de Aprovação Cliente sem Estabelecimento de Aprovação Erro Conexão não Estabelecida Conexão não Estabelecida Erro Conexão AVS não Estabelecida Conexão AVS não Estabelecida Erro Sem Servidor Aprovação Sem Servidor Aprovação Erro IP não permitido IP não permitido Erro Última Aprovação para o cartão tem menos do que 5 Última Aprovação para o cartão tem menos do que 5 minutos minutos Erro Cartão com 3 tentativas não aprovadas Cartão com 3 tentativas não aprovadas Erro Parâmetros Incorretos Parâmetros Incorretos Erro Código Cliente Inválido Código Cliente Inválido Erro Código de Cliente Forjado Código de Cliente Forjado Erro Modo de Operação Inválido Modo de Operação Inválido Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 25 4. Cartão de Crédito – Pedido de Captura – CAP 4.1. Descrição A diretiva de execução CAP efetua a captura de uma transação. Entendese por captura o processo de confirmação de uma transação, o que caracteriza a venda efetivada, sendo realizado assim, o débito no cartão de crédito do cliente. De acordo com os padrões ISO 8583, todas as transações aprovadas pelas Administradoras de Cartões de Crédito devem ser capturadas (confirmadas) pela aplicação do Lojista. Caso a transação não seja capturada (confirmada) pela aplicação do Lojista, no prazo estipulado pelas Administradoras de Cartões Crédito, a mesma será automaticamente desfeita, não havendo assim o débito efetivo no cartão de crédito do cliente, essa informação será exibida no campo “Data Hora Cancelamento”do Extrato do Aprova Fácil. 4.2. Métodos de Envio Os métodos de envio dos parâmetros podem ser o POST ou GET, utilizando conexões HTTP ou HTTPS, já que não são trafegados dados sigilosos. 4.3. URLs 4.3.1. Servidor principal: 4.3.2. Servidor de teste: Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 26 Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 4.4. Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Nome Descrição NumeroDocumento Transação Formatação Identificação da venda Até 50 caracteres pela loja. Número da transação 14 caracteres numéricos Exemplo 123ABC 73263500055432 Numérico com 2 Obrigatório Não Se NumeroDocumento for nulo Não casas decimais ValorDocumento* Valor a ser capturado (separador 123.56 decimal é o ponto) * Utilizado apenas quando um valor parcial necessita ser capturado. Apenas algumas tecnologias de conectividade permitem a captura parcial. Entre em contato conosco para maiores informações. 4.5. Exemplos de Requisição GET 4.5.1. Captura utilizando o número documento gerado pelo estabelecimento 4.5.2. Captura Utilizando o número da transação gerado pelo Aprova Fácil Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 27 Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 4.6. Exemplo de Resultados 4.6.1. Captura com Sucesso <ResultadoCAP> <ResultadoSolicitacaoConfirmacao> Confirmado%2073263500055432 </ResultadoSolicitacaoConfirmacao> <ComprovanteAdministradora></ComprovanteAdministradora> </ResultadoCAP> 4.6.2. Captura com Erro <ResultadoCAP> <ResultadoSolicitacaoConfirmacao> Erro%20%20Transa%E7%E3o%20a%20confirmar%20n%E3o%20encontrada%20ou %20jE1%20confirmada </ResultadoSolicitacaoConfirmacao> <ComprovanteAdministradora></ComprovanteAdministradora> </ResultadoCAP> 4.7. Resultado de Captura com Sucesso O resultado de uma transação de captura bem sucedida começará com a palavra “Confirmado”, seguida de um carácter de espaço, e do número de transação Aprova Fácil. 4.8. Resultados de Erro Comuns Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 28 Texto do Resultado Descrição Erro Transação Inválida Transação Inválida Erro Transação a confirmar não encontrada ou já confirmada Transação a confirmar não encontrada ou já confirmada Erro IP não permitido IP não permitido Erro Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY Adquirinte YYY Erro Estabelecimento não habilitado para a Bandeira XXX XXX não habilitada para o estabelecimento Adquirinte YYY Erro Captura Já Efetuada Captura já efetuada Erro Parâmetros Incorretos Parâmetros incorretos Erro Código Cliente Inválido Código cliente inválido Erro Código de Cliente Forjado Código de cliente forjado Erro Modo de Operação Inválido Modo de operação inválido Erro Conexão para confirmação não Estabelecida Conexão para confirmação não estabelecida Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 29 5. Cartão de Crédito – Cancelamento de Transações – CAN 5.1. Descrição A diretiva de execução CAN é utilizada no processo de cancelamento da transação. O cancelamento de uma transação somente poderá ser realizado quando a mesma for aprovada pela Administradora e confirmada pelo lojista. Por isso, para que o Aprova Fácil possa realizar o cancelamento, este deve ser solicitado no mesmo dia em que a transação foi processada, ou seja, foi confirmada pela Administradora. 5.2. Métodos de Envio O método de envio utilizado pode ser o POST ou GET e as informações podem ser enviadas através de HTTP ou HTTPS, já que não são trafegados dados sigilosos. 5.3. URLs 5.3.1. Servidor principal: 5.3.2. Servidor de teste: Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 30 5.4. Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Nome Descrição NumeroDocumento Transacao Formatação Identificação da venda Até 50 caracteres pela loja. alfanuméricos. Número da transação 14 caracteres numéricos Exemplo 123ABC 73263500055432 numérico com 2 ValorDocumento* Valor a ser cancelado dígitos decimais (separador decimal Obrigatório Não Se NumeroDocumento for nulo Não 123.56 é o ponto) * Utilizado apenas quando um valor parcial necessita ser cancelado. Apenas algumas tecnologias de conectividade permitem o cancelamento parcial. Entre em contato conosco para maiores informações. 5.5. Exemplos de Requisição 5.5.1. Cancelamento utilizando o número do documento gerado pelo estabelecimento 5.5.2. Cancelamento Utilizando o ID da Transação Aprova Fácil Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 31 5.6. Resultado XML <ResultadoCAN> <ResultadoSolicitacaoCancelamento></ResultadoSolicitacaoCancelamento> <NSUCancelamento></NSUCancelamento> </ResultadoCAN> 5.7. Resultado das Tags XML Nome ResultadoCAN Descrição Tag Raiz XML ResultadoSolicitacaoCancelamento Descrição do resultado do Formatação Número de cancelamento da Obrigatório N/A N/A sim texto varchar veja tabela sim pedido de cancelamento NSUCancelamento Amostra abaixo 6 dígitos numéricos 123456 não Administradora 5.8. Exemplos de Resultados 5.8.1. Cancelamento Online Com Sucesso <ResultadoCAN> <ResultadoSolicitacaoCancelamento> Cancelado%2073263500055432 </ResultadoSolicitacaoCancelamento> <NSUCancelamento> 123456 </NSUCancelamento> </ResultadoCAN> Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 32 5.8.2. Cancelamento Marcado para Processamento com Sucesso <ResultadoCAN> <ResultadoSolicitacaoCancelamento> Cancelamento%20marcado%20para%20envio%2073263500055432 </ResultadoSolicitacaoCancelamento> <NSUCancelamento> 123456 </NSUCancelamento> </ResultadoCAN> 5.8.3. Erro de Cancelamento OnLine <ResultadoCAN> <ResultadoSolicitacaoCancelamento> Erro%20%20Transa%E7%E3o%20inv%E1lida </ResultadoSolicitacaoCancelamento> <NSUCancelamento></NSUCancelamento> </ResultadoCAN> 5.8.4. Erro na Marcação do Cancelamento para Processamento <ResultadoCAN> <ResultadoSolicitacaoCancelamento> Erro%20%20Transa%E7%E3o%20inv%E1lida </ResultadoSolicitacaoCancelamento> <NSUCancelamento></NSUCancelamento> </ResultadoCAN> Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 33 5.9. Resultado de Cancelamento com Sucesso O resultado de uma transação cancelada com sucesso será a mensagem “Cancelamento OK”. 5.10. Resultados de Erros Comuns NSU Cancelamento Texto do Resultado Descrição Erro Transação Inválida Transação Inválida Erro Transação a cancelar não encontrada ou já cancelada Transação a cancelar não encontrada ou já cancelada Erro IP não permitido IP não permitido Erro Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY Adquirinte YYY Erro Estabelecimento não habilitado para a Bandeira XXX XXX não habilitada para o estabelecimento Adquirinte YYY Erro – Cancelamento Já Efetuado Cancelamento já efetuado Erro Parâmetros Incorretos Parâmetros incorretos Erro Código Cliente Inválido Código cliente inválido Erro Código de Cliente Forjado Código de cliente forjado Erro Modo de Operação Inválido Modo de operação inválido Erro Conexão para cancelamento não Estabelecida Conexão para cancelamento não estabelecida Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 34 6. Cartão de Crédito – Call Back de Reembolso 6.1. Descrição Reembolso é um cancelamento feito em dias posteriores à aprovação da transação. A funcionalidade “Reembolso” requer prévio cadastro, pois não é ativada por default quando o estabelecimento é cadastrado em nosso sistema. É necessário enviar email para [email protected] informando que deseja ativar o reembolso. Não há reembolso sem que a transação tenha sido Aprovada e Confirmada pelo estabelecimento. 6.2. Métodos de Envio O método de envio utilizado pode ser o POST ou GET e as informações podem ser enviadas através de HTTP ou HTTPS. 6.3. URLs 6.3.1 Servidor de Produção: 6.4. Parâmetros de Requisição Nome NumeroDocumento* Transacao Descrição Formatação Identificação da Até 50 caracteres alfanuméricos. venda pela loja. Número da Exemplo 123ABC 14 caracteres numéricos Obrigatório Não Sim, se o 73263500055432 NumeroDocumento transação não for enviado Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 35 Nome Descrição ValorDocumento** Formatação Valor a ser Numérico, sendo as casas reembolsado decimais separadas por ponto (.) Exemplo 123.56 Obrigatório Sim *Se o valor informado ao parametro NumeroDocumento for diferente do valor informado na solicitação de aprovação, este novo valor será devolvido dentro do parâmetro NumeroDocumento no retorno do reembolso. Em caso de múltiplos reembolsos para a mesma transação o parâmetro NumeroDocumento será utilizado como identificador de cada solicitação de reembolso, tornandoo obrigatório. ** Ao solicitar um reembolso parcial, informe o valor desejado ao parâmetro ValorDocumento. Para uma mesma transação, pode ser efetuado mais do que um reembolso parcial. O valor total dos reembolsos parcias não pode ultrapassar o valor da transação original. 6.5.Resposta a uma Solicitação de Reembolso Bem Sucedida A mensagem "Cancelamento marcado para envio XXXXXXXXXXXXXX" aparecerá, designando uma solicitação de reembolso bem sucedida, segundos após a requisição deste. Exemplo: <ResultadoCAN> <ResultadoSolicitacaoCancelamento> Cancelamento marcado para envio XXXXXXXXXXXXXX </ResultadoSolicitacaoCancelamento> <NSUCancelamento> XXXXXXXXXXXXXX </NSUCancelamento> </ResultadoCAN> XXXXXXXXXXXXXX = Número da Transação Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 36 7.Cartão de Crédito – Resultado de Reembolso 7.1. Descrição O resultado de um reembolso não é síncrono. O resultado de um reembolso é enviado para uma URL de retorno. 7.2. Métodos de Envio O método de envio utilizado será o GET e as informações podem ser enviadas através de HTTP ou HTTPS. 7.3. Envio do Resultado de Reembolso O resultado do processamento de um reembolso será enviado pelo gateway de pagamentos para a URL de retorno de reembolso do estabelecimento. O lojista deverá ter um script apto a receber o resultado de reembolso. A URL deste script deverá ser informada a Cobre Bem Tecnologia no momento em que a habilitação de reembolso for solicitada, através de e mail para [email protected]. 7.4. Exemplo de chamada http://www.seusite.com.br/callbackcancelamento.asp? Transacao=98765432109876&NumeroDocumento=12345678&ResultadoSolicitacaoCancelamento=Mensagem+da+A dministradora&NSUCancelamento=56789012345678 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 37 7.5. Descrição dos parâmetros Nome Descrição Formatação Número da 14 caracteres Transacao transação numéricos Identificação NumeroDocumento da venda pela loja. Até Exemplo 73263500055432 50 caracteres alfanumérico Obrigatório Sim Sim 123ABC s ResultadoSolicitaca Resultado do Texto Sucesso “Cancelado XXXXXXXXXXXXXX” Sim oCancelamento processamento varchar onde XXXXXXXXXXXXXX é o número da do reembolso transação na Cobre Bem Tecnologia. Falha “Erro YYYYYYYYYYYYYYYYYY” onde YYYYYYYYYYYYYYYYYY é a mensagem de erro retornada pela administradora Número de 6 NSUCancelamento dígitos 123456 Não* cancelamento numéricos da administradora * O NSU de cancelamento é enviado para a URL de retorno do estabelecimento somente quando esse dado é retornado para a Cobre Bem pelo adquirente. 7.6. Confirmação de Recebimento de Retorno A URL de retorno de reembolso do estabelecimento deverá responder com o string “OK”, sem as aspas, para indicar que recebeu o resultado. Caso contrário, o resultado continuará a ser enviado pelo gateway de pagamentos, pois ele considerará que os dados não foram recebidos pelo aplicativo do estabelecimento. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 38 8. Boleto Bancário – Pedido de Emissão – BOL 8.1. Descrição O pedido de emissão irá retornar um boleto bancário em PDF para o script do cliente. Nosso retorno padrão é em PDF. 8.2. Métodos de Envio O método de envio utilizado pode ser POST ou GET por HTTPS. 8.3. URL's 8.3.1. Servidor principal: 8.3.2. Servidor teste: Nota: <usuario> deverá ser substituído pelo nome do usuário do Aprova Fácil. 8.4. Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 39 Nome CCID Descrição Formatação Identifica a conta corrente a ser Até 15 caracteres utilizada para a geração do boleto NumeroDocumento Identificação da venda pela loja. Exemplo Obrigatório 1234 Sim 123ABC Sim 123.56 Sim 20130412 Não 3 Não S Alterar S Não 14 dígitos numéricos 12345678123412 11 dígitos numéricos 12345678912 Fulano de Tal alfanuméricos. Até 50 caracteres alfanuméricos. Numérico, sendo as ValorDocumento Valor da transação casas decimais separadas por ponto (.) DataVencimento Data de vencimento desejada para o boleto Número de dias a serem adicionados a PrazoVencimento data corrente e gerar uma data de validade VencimentoDiaUtil CNPJCPFSacado Altera o vencimento para o proximo dia util CPF ou CNPJ do cliente aaaammdd Até 04 dígitos numéricos NomeSacado Nome do cliente Até 40 caracteres EnderecoSacado Endereço do cliente Até 40 caracteres Rua Não Não do cliente,123 Não 05 dígitos numéricos + CEPSacado CEP do cliente travessão + 3 dígitos 12345008 Não numéricos CidadeSacado Nome da cidade do cliente Até 30 caracteres Rio de Janeiro Não EstadoSacado Estado do cliente 02 caracteres RJ Não Endereço de email do sacado até 64 caracteres EnderecoEmailSac ado PercentualJurosDia PercentualMulta Percentual de juros a ser cobrado por dia de atraso no pagamento Percentual de multa a ser cobrado por atraso no pagamento [email protected] .br Não Numérico, sendo as casas decimais 0.99 Não 1.39 Não separadas por ponto (.) Numérico, sendo as casas decimais separadas por ponto (.) Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 40 Nome Descrição Código HTML que será exibido nas InstrucoesCaixa instruções para o caixa demonstrativo do recibo do sacado SacadorAvalista Nome do avalista quando este existir Valor do desconto a ser concedido sobre o valor do documento ValorOutrosAcresc Valor dos acréscimos a serem imos Exemplo Obrigatório <b>não receber código HTML após vencimento Não </b> Código HTML que será exibido no Demonstrativo ValorDesconto Formatação somados ao valor do documento Referente código HTML compra a de Não produtos X Caracteres Fulano de Tal Não 0.99 Não 10 Não RC Não Numérico, sendo as casas decimais separadas por ponto (.) Numérico, sendo as casas decimais separadas por ponto (.) Tipo de documento a ser impresso no EspecieDocumento boleto. Se não for informado, Caracteres assumirá o valor padrão “RC” 8.5. Exemplo de Requisição O pedido de emissão (/ BOL) deve ser originado no servidor do cliente. A fim de evitar requisições de emissões de Boletos não autorizadas apenas o IP do servidor do cliente será habilitado para essa funcionalidade. Nota: Se um pedido não autorizado de emissão de Boleto for identificado, a seguinte mensagem de erro será retornada: "IP Localidade: Não Autorizado", conforme indicado nos itens: 8.6.2 e 8.7 8.6. Resultados 8.6.1. Resultados Bem Sucedidos É retornado o PDF do boleto para a loja. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 41 8.6.2. Resultados Erro na Transação É retornada para o navegador do cliente uma string (HTML) tag <font color="#FF0000"> <b>. Abaixo está um exemplo genérico: <html><title>Cobre Bem Tecnologia Aprova Fácil</title> <body><table><tr><td colspan=2><center><font color="#FF0000"><b>Cliente não encontrado.</b></font></center></td></tr></table> </body></html> 8.7. Resultados de Erros Comuns Resultado Descrição Ação Sugerida Cliente não encontrado. Cliente não encontrado Confira nome de usuário na URL CCID não informado. CCID não informado Verifique o parâmetro CCID Conta corrente boleto não Conta corrente boleto não encontrado Verifique o parâmetro CCID encontrado. Conta corrente boleto sem licença. Conta corrente boleto sem licença Contate nosso suporte IP Não Autorizado. IP Não Autorizado Contate nosso suporte Cliente boleto não encontrado. Estabelecimento não habilitado para Contate nosso suporte boleto * Por favor, informenos se você receber uma mensagem de erro diferente das listadas acima, através do email [email protected] e relate a mensagem de erro exatamente como a recebeu. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 42 9. Transferências Bancárias On Line – Pedido de Aprovação TRX 9.1. Descrição O pedido de aprovação será realizado toda vez que a aplicação do Lojista necessitar obter aprovação financeira de uma venda, por meio de transferência eletrônica on line. O pedido de transferência eletrônica on line retornará um código XML contendo um HTML que redicionará o navegador do cliente para o site do banco selecionado. 9.2. Métodos de Envio O método de envio de dados deve ser via POST para um link em protocolo HTTPS. 9.3. URLs 9.3.1. Servidor principal: Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 9.4. Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Nome NumeroDocumento Descrição Formatação Identificação da venda pela Até 50 caracteres alfanuméricos. loja. QuantidadeParcelas Quantidade de parcelas Valor válido: 01 Exemplo 123ABC Não 01 Sim Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ Obrigatório 43 Nome Descrição ValorDocumento Valor da transação Formatação Numérico, sendo as casas decimais separadas por ponto (.) Exemplo Obrigatório 123.56 Sim BRADESCO Sim Valores válidos são: Bandeira Nome do banco BBRASIL / BANRISUL / BRADESCO / HSBC / ITAU CNPJCPFSacado CNPJ ou CPF do sacado 14 dígitos numéricos 12345678123412 11 dígitos numéricos 12345678912 Não Glossário para o item 9.4 da tabela: BBRASIL = Banco do Brasil BANRISUL = Banco do Estado do Rio Grande do Sul 9.5. Requisição O pedido de aprovação Transferência Bancária Online (/ TRX) devem ser originados de servidor do cliente. A fim de evitar bancários online pedidos de aprovação de transferência não autorizada, IP apenas do servidor cliente será habilitado para essa funcionalidade. Nota: No caso de um pedido de aprovação não autorizado Transferência Bancária Online ser identificado, a seguinte mensagem de erro será retornada: "IP Localidade: Não Autorizado", conforme indicado nos itens: 9.6.2.2 e 9.7.2. 9.6. Exemplo de Resultados 9.6.1. Chamada de inicialização bem sucessida A resposta irá retornar um XML com o código HTML embutido na tag <ResultadoSolicitacaoAprovacao> . O HTML irá variar de acordo com o Banco selecionado. Desenvolvedor: Este HTML irá redirecionar automaticamente o comprador para o ambiente do Banco. Abaixo está um exemplo genérico: Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 44 <ResultadoAPC> <TransacaoAprovada>False</TransacaoAprovada> <ResultadoSolicitacaoAprovacao> <html><body onLoad="document.forms[0].submit();"><p> </p><p> </p><p><center>Aguarde um instante...</center></p><form action=https://www.bancoselecionado.com.br method=post><input type=hidden name=TRANSACAO value=1><input type=hidden name=FILIACAO value=123><input type=hidden name=NUMPEDIDO value=123456></form></body></html> </ResultadoSolicitacaoAprovacao> <CodigoAutorizacao></CodigoAutorizacao> <Transacao>73314072604262</Transacao> <CartaoMascarado>Cartao Nao Informado</CartaoMascarado> <NumeroDocumento>123ABC</NumeroDocumento> <ComprovanteAdministradora></ComprovanteAdministradora> <NacionalidadeEmissor></NacionalidadeEmissor> <ResultadoAVS></ResultadoAVS> <EnderecoAVS> <Endereco></Endereco> <Numero></Numero> <Complemento></Complemento> <Cep></Cep> </EnderecoAVS> </ResultadoAPC> 9.6.2. Erro de inicialização de Chamadas 9.6.2.1. Em XML A mensagem de erro aparecerá na tag XML <ResultadoSolicitacaoAprovacao>. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 45 Abaixo um exemplo genérico: <ResultadoAPC> <TransacaoAprovada>False</TransacaoAprovada> <ResultadoSolicitacaoAprovacao>Erro Numero Parcelas Invalido</ResultadoSolicitacaoAprovacao> <CodigoAutorizacao></CodigoAutorizacao> <Transacao></Transacao> <CartaoMascarado>Cartao Nao Informado</CartaoMascarado> <NumeroDocumento>123ABC</NumeroDocumento> <ComprovanteAdministradora></ComprovanteAdministradora> <NacionalidadeEmissor></NacionalidadeEmissor> <ResultadoAVS></ResultadoAVS> <EnderecoAVS> <Endereco></Endereco> <Numero></Numero> <Complemento></Complemento> <Cep></Cep> </EnderecoAVS> </ResultadoAPC> 9.6.2.2. Em HTML A mensagem de erro irá aparecer no HTML tag <font color="#FF0000"> <b>. Abaixo um exemplo genérico: <html><title>Cobre Bem Tecnologia Aprova Fácil</title> <body><table><tr><td colspan=2><center><font color="#FF0000"><b>Cliente não encontrado.</b></font></center></td></tr></table> </body></html> Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 46 9.7. Resultados de Erros Comuns 9.7.1. Em XML con Tag: <ResultadoSolicitacaoAprovacao> Resultado Descrição Erro Conexão não Estabelecida Ação Sugerida Conexão não estabelecida Tente novamente [XXXXXX][IP XXXXXX] Erro Estabelecimento não cadastrado para Bandeira não habilitada no usuário do a Bandeira XXXXXX Aprova Fácil Erro Numero Parcelas Invalido Número Parcelas Invalido Contate nossa equipe de suporte Verificar parâmetro QuantidadeParcelas Erro Read Timeout Tempo Expirado Tente novamente Erro Valor deve ser maior que zero Valor> 0 Verificar parametro ValorDocumento Erro YYYYYY Mensagem de Erro Variável Notifique o suporte * Glossário para o item 9.7.1 da Tabela: XXXXXX = Texto Variável YYYYYY = Messagem Não Mapeada 9.7.2. Em HTML on Tag: <font color="#FF0000"><b> Resultado Descrição Ação Sugerida Cliente não encontrado. Cliente não encontrado Confira nome de usuário na URL IP Não Autorizado. IP Não Autorizado Contate nossa equipe de suporte Método não suportado. Método não suportado Confira método de envio * Por favor, informenos se você suspeitar que a mensagem de erro recebida não foi gerada pelo adquirente, mas a partir de nosso sistema, através do email [email protected] e informe a mensagem de erro recebida com exatidão. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 47 10. Transferências Bancárias On Line – Retorno de Confirmação de Pedido 10.1. Descrição O retorno de uma Transferência será feita do Aprova Fácil para o site do Lojista. O desenvolvedor deverá fornecer uma URL para receber o POST ou GET dos servidores do Aprova Fácil, esta conterá a informação de confirmação de pagamento do pedido de transferência bancária on line. 10.2. Métodos de Envio O método pode ser o POST ou GET, e as informações podem ser enviadas através de HTTP ou HTTPS. 10.3. URL Segue um exemplo: https://pagamento.lojacliente.com/RetornoTransacao.php 10.4. Parâmetros de Retorno Nota: A ordem de envio dos parâmetros é aleatória evitando assim, possíveis vulnerabilidades na aplicação do lojista. Mais informações sobre este assunto podem ser obtidas em: https://media.blackhat.com/bheu11/Marco_Balduzzi/BlackHat_EU_2011_Balduzzi_HTTP_ParameterSlides.pdf (Última data de acesso: 29/09/2011) Nome Descrição Formatação Exemplo Obrigatório NumeroDocumento Identificação da venda do Lojista Até 50 caracteres 123ABC Não TransacaoAprovad Resultado da transação True ou False True Sim Texto varchar N12345 a CodigoAutorizacao Código de autorização devolvido pelo banco ResultadoSolicitaca Descrição do resultado da Texto varchar Autoriza%E7%E3o oAprovacao %20 requisição Sim se aprovada Não %2073433262195404 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 48 Nome Descrição Formatação Texto de 14 dígitos Exemplo Transacao ID da transacao Aprova Fácil CartaoMascarado Número do Cartão de Crédito Até 19 dígitos Cartao%20Nao Mascarado. Nos retornos de numéricos 73263868827369 Obrigatório Sim Não %20Informado transferência, o resultado será sempre “Cartao%20Nao %20Informado” ValorDocumento Valor da transação informado numérico com 2 123.56 Não 01 Não BRADESCO Não 00 Não 00 Não pelo lojista no momento da dígitos decimais requisição de aprovação (separador decimal é o ponto) QuantidadeParcelas Quantidade de parcelas 2 dígitos numéricos informada pelo lojista no momento da solicitação de aprovação. Bandeira Nome do banco informado pelo Válores válidos são: lojista no momento da BBRASIL solicitação de aprovação. BANRISUL BRADESCO HSBC ITAU MesValidade Mês em que o cartão expira. Nos 2 dígitos numéricos retornos de transferência, seu valor será sempre igual a “00” AnoValidade Ano em que o cartão expira. Nos 2 dígitos numéricos retornos de transferência, seu valor será sempre igual a “00” NumeroSequencial N /A Sempre em branco Não Sempre em branco Não Unico NumeroControleRe N /A de Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 49 Nome ResultadoAVS Descrição Formatação Exemplo Obrigatório Resultado da verificação de 01 caracter maiúsculo F Não endereço. Nos retornos de transferência, seu valor será sempre “F” NUMPEDIDO Número que bancos utilizam 14 caracteres 73263868827369 Não para identificar a transação. 10.5. Exemplo de Retorno https://pagamento.lojacliente.com/RetornoTransacao.php? NumeroDocumento=123ABC&TransacaoAprovada=True&CodigoAutorizacao=123456&ResultadoSolicitacao Aprovacao=Autoriza%E7%E3o%20 %2073433262195404&Transacao=73561234567898&CartaoMascarado=Cartao%20Nao %20Informado&ValorDocumento=123.56&QuantidadeParcelas=01&Bandeira=BRADESCO&MesValidade=0 0&AnoValidade=00&NumeroSequencialUnico=&NumeroControleRede=&ResultadoAVS=F&NUMPEDIDO= 73561234567898 10.6. Resultados de Erros Comuns Texto Descrição Erro Transação Inválida Transação inválida Erro Transação a cancelar não encontrada ou já cancelada Transação a cancelar não encontrada ou já cancelada Erro – Cancelamento Já Efetuado Cancelamento já efetuado Erro Conexão para cancelamento não Estabelecida Conexão para cancelamento não estabelecida Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 50 11. Débito Automático em Conta Corrente – Pedido de Aprovação – DEB 11.1. Descrição O pedido de aprovação será realizado toda vez que a aplicação do Lojista necessitar obter aprovação financeira de uma venda, por meio de débito automático em conta corrente. O Aprova Fácil envia um arquivo de remessa ao Banco, para que este realize o processamento dos débitos. 11.2. Métodos de Envio O método utilizado deve ser o POST ou GET, e as informações devem ser enviadas através de HTTPS, já que serão trafegados dados sigilosos. 11.3. URL 11.3.1. Servidor principal: 11.3.2. Servidor teste: Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 11.4. Parâmetros de Requisição Nota: Parâmetros opcionais podem não ser informados ou informados sem valor caso não deseje utilizálos. Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 51 Nome NumeroDocumento Descrição Formatação Identificação da venda Até pela loja. 50 Exemplo caracteres alfanuméricos. 123ABC Obrigatório Sim Numérico, sendo as casas ValorDocumento Valor da transação decimais separadas por 123.56 Sim ponto (.) NumeroBanco Identifica o Banco 3 digitos Código da agência da CodigoAgencia conta corrente a ser debitada ContaCorrente TitularContaCorrente Somente dígitos de 0 a 9, P ou X Número da conta Somente dígitos de 0 a 9, P corrente a ser debitada Nome do titular da conta corrente a ser debitada ou X Até 40 caracteres 001 Sim 12707 Sim 56749 Sim Cliente da Loja Sim 11 digitos se CPF CNPJCPFSacado CPF ou CNPJ do Sacado 14 digitos se 12345678123412 CNPJ12345678123412 12345678912 Sim 12345678912 DataNascimentoSacado Agendamento TransacaoAnterior DiaParaAgendar Data de nascimento do sacado Utilizado para incluir ou excluir um agendamento ID transação Aprova Facil 20071027 Não Apenas um caracter: I – Incluir/ E – Excluir/ A I Não Atualizar Se 14 digitos numéricos 78712879871121 Agendamento=A ou E Dia de cada mês em que será feito o débito QuantidadeMesesParaA Quantidade de meses gendar aaaammdd para agendar dd 09 2 dígitos inteiros 08 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ Se Agendamento=I Se Agendamento=I 52 Nome Descrição NumeroTentativasNao Aprovado Formatação Exemplo Número de tentativas para a transação ser 2 dígitos inteiros 04 aprovada QuantidadeDiasEntreTe Quantidade de dias entre ntativas cada tentativa 2 dígitos inteiros 03 Obrigatório Se Agendamento=I Se Agendamento=I Data para qual o débito deve ser programado. Esta data deve ser maior DataVencimento ou igual ao prazo aaaammdd 20080820 Não mínimo permitido para o convênio em cada Banco. * Se os valores de A ou E forem informados para o parâmetro marcado Agendamento, o parâmetro marcado TransacaoAnterior deve ser usado. Nota: O parâmetro NumeroDocumento não pode ter valores repetidos. Nota: Cada banco possui um formato diferente para as propriedades CodigoAgencia e ContaCorrente. Entre em contato conosco para saber como serão preenchidas. 11.5. Exemplo de Requisição Visualize o trecho de código abaixo: Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 53 Nota: <usuario> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil. 11.6. Exemplo de Resultados 11.6.1. Dados Corretos <Resposta><Transacao>XXXXXXXXXX</Transacao></Resposta> Onde: XXXXXXXXXX é um número único gerado para identificar a transação. 11.6.2. Dados Incorretos <Resposta><Erro> YYYYYYYYYY</Erro></Resposta> Onde: YYYYYYYYYY é a descrição do erro. 11.6.3. Exemplos de resposta <Resposta><Transacao>73127890046539</Transacao></Resposta> <Resposta><Erro>Conta Corrente Inválida</Erro></Resposta> <Resposta><Erro>Banco não Suportado</Erro></Resposta> <Resposta><Erro>Agência Inválida</Erro></Resposta> Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 54 12. Diagrama de Funcionamento Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 55 Aprova Fácil WebService Integração Versão 1.4.14.7.25 http://www.cobrebem.com/ 56
Download
