Manual técnico v2.2 2015/10
Índice 1. INTRODUÇÃO... 3 2. DESCRIÇÃO... 3 3. INTEGRAÇÃO DO SISTEMA... 4 3.1 DESCRIÇÃO... 4 3.2 INTEGRAÇÃO... 5 3.2.1. Geração de referências... 5 getreferencemb...5 getreferencemb2...7 getreferenceps...8 getreferenceps2...9 3.2.2. Métodos para obter informação sobre referências... 10 getinfo...10 getinforeference...11 4. NOTIFICAÇÃO DE PAGAMENTO...11 4.1 CHAMADA DE URL DO PARCEIRO... 11 5. EXEMPLOS DE CÓDIGO...12 6. INFORMAÇÃO ADICIONAL...13 2
1. Introdução O sistema Hipay Comprafácil foi desenvolvido com o objectivo de ser o mais flexível possível, nomeadamente na forma como os parceiros lhe acedem para obter referências MULTIBANCO e PayShop para pagamento. A geração de referências pode ser feita de três formas distintas: através de SMS, através da Internet (sendo necessários um username e password para aceder ao backoffice) e através da utilização de webservices. Esta última forma de acesso tem como objectivo a integração desta funcionalidade nas aplicações do parceiro que necessitam de pagamentos, como sejam sites de comércio electrónico. Esta integração deve ser executada por um técnico ou equipa com o know-how necessário na utilização desta tecnologia. É precisamente sobre última forma de acesso, a utilização de webservices, que este documento fornece mais informação. 2. Descrição Os webservices estão disponíveis nos endereços: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx para referências que não têm tempo limite para pagamento e podem ser pagas múltiplas vezes (presentemente isto acontece com referências da entidade 10241); https://hm.comprafacil.pt/sibsclick2/webservice/comprafacilws.asmx para referências que têm tempo limite para pagamento e apenas podem ser pagas uma vez (presentemente isto acontece com as referências da entidade 11249). Para a utilização destes webservices o parceiro deve ter um username e password fornecidos pela Hipay. Existem também webservices de teste que podem ser usados pelo parceiro para efeitos de desenvolvimento. Para ter acesso a eles o parceiro deve contactar a Hipay pelo e-mail portugal@hipay.com. 3
3. Integração do sistema 3.1 Descrição A integração entre o Hipay Comprafácil e os sistemas dos parceiros é bastante simples e baseada no uso de webservices. Os webservices são usados na integração de sistemas e comunicação entre aplicações. Desta forma é possível que diferentes aplicações construídas com diferentes tecnologias possam interagir. Esta tecnologia é baseada nos padrões XML e SOAP. A informação é transferida no formato XML e encapsulada pelo protocolo SOAP. O transporte é feito via HTTPS. Para a utilização de webservices na construção das aplicações, os parceiros devem usar tecnologias que as suportem tais como JAVA, PHP,.NET ou outras. Normalmente estas tecnologias têm componentes específicos para trabalharem com webservices. Geração de referências Os webservices permitem a geração de referências no sistema Hipay Comprafácil (ou seja, referências MULTIBANCO e/ou PayShop). Em cada chamada ao método apropriado devem ser fornecidos alguns parâmetros obrigatórios e podem também ser fornecidos vários outros para facilitar a subsequente gestão das referências e pagamentos. Estes podem ser por exemplo a especificação de onde o pedido foi originado ou um identificador no sistema do parceiro, entre outros. Depois de cada chamada a seguinte informação é devolvida à aplicação do parceiro (para referências MULTIBANCO): Entidade Referência Valor Esta informação deve ser comunicada ao cliente final de uma forma conveniente (mostrando no ecrã, enviando por e-mail, etc.) pelo parceiro. É da responsabilidade do parceiro essa comunicação. Além desta informação é devolvida uma mensagem de erro em caso da geração não ser bem-sucedida. É importante notar que para a entidade cujas referências não têm tempo limite para pagamento e podem ser pagas múltiplas vezes, quando um parceiro necessita de uma nova referência para um determinado cliente final e para um valor já pago por este anteriormente, em vez de pedir uma nova ao Hipay Comprafácil, pode em vez de isso fornecer uma antiga para novo pagamento. Da perspectiva do parceiro esta abordagem tem a óbvia vantagem de não tem de contactar o Hipay Comprafácil e ter de imediato uma referência disponível para novo pagamento. Ao usar esta abordagem o parceiro deve controlar quantas vezes essa referência foi paga. Esta abordagem não é possível para a entidade cujas referências só podem ser pagas uma vez. Relativamente à entidade cujas referências têm tempo limite para pagamento, é importante referir que a informação sobre a data limite de pagamento deve ser dada ao cliente final juntamente com a informação referida anteriormente. Além disso é importante referir também 4
que o webservice não devolve a informação relativa à data limite de pagamento. Esta informação deve ser calculada pelo parceiro depois de chamar o método do webservice para a geração da referência, tendo como base o valor especificado no parâmetro timelimitdays. Por exemplo, se o parceiro especificou 3 no parâmetro timelimitdays, então deve comunicar ao cliente final uma data de 3 dias no futuro. Referências PayShop Ambos os websevices têm métodos para gerar referências MULTIBANCO e métodos para gerar referências PayShop. As referências MULTIBANCO têm características diferentes, tal como descrito anteriormente (relativamente a data limite de pagamento e ao número de pagamentos aceites), dependendo do webservice utilizado para as gerar. As referências PayShop têm as mesmas características, independentemente do webservice que foi usado para as gerar. Assim, as referências PayShop de ambos os webservices: Têm data limite para pagamento fixa de 30 dias; os respectivos métodos utilizados para as gerar devolvem a data limite para pagamento (em oposição às MULTIBANCO para as quais é necessário um cálculo posterior). 3.2 Integração O primeiro passo para a integração será a definição da linguagem de programação a utilizar, como.net, PHP, ou outra que suporte o uso de webservices. É importante notar que ambos os webservices têm os mesmos métodos e parâmetros e funcionam da mesma forma. Os webservices fornecem vários métodos para diferentes situações: geração de novas referências e obtenção de informação sobre o estado das referências. 3.2.1. Geração de referências Para a geração de referências estes webservices dispõem de quatro métodos: getreferencemb, getreferencemb2, getreferenceps e getreferenceps2. getreferencemb Obtém uma nova referência MULTIBANCO para pagamento especificando o montante. O parâmetro timelimitdays especifica o número total de dias em que a referência é pagável. Para a entidade sem data limite para pagamento este valor é ignorado. Este método é o mais usado pelos parceiros do Hipay Comprafácil. Parâmetros de entrada 5
origin: Este parâmetro é utilizado para guardar o número de telefone quando uma referência é solicitada através de SMS. Se o pedido é recebido através deste webservice pode ser usada como descritivo para a origem do pedido, por exemplo o URL da aplicação que originou o pedido. Este campo pode ser também utilizado para armazenar o URL no sistema do parceiro que o Hipay Comprafácil irá chamar quando ocorre o pagamento (caso esta funcionalidade esteja activa para a conta do parceiro). Não é obrigatório. username/password: dados de acesso ao webservice. Obrigatório. amount: montante (em Euros) usado para a geração da referência. Obrigatório. additionalinfo: informação adicional que pode ser passada ao Hipay Comprafácil. Não obrigatório. name: especifica o nome do cliente final para quem a referência é gerada (o comprador a pessoa que paga a referência). Não obrigatório. address: endereço do cliente final. Não obrigatório. postcode: código postal do cliente final. Não obrigatório. city: localidade do cliente final. Não obrigatório. NIC: NIF do cliente final. Não obrigatório. externalreference: se a referência MULTIBANCO tem um identificador correspondente no sistema do parceiro, este parâmetro pode ser utilizado para o armazenar. Não obrigatório. contactphone: telefone de contacto do cliente final. Não obrigatório. email: endereço de e-mail do cliente final. O parceiro será responsável por recolher os endereços de e-mail dos seus clientes para os poder fornecer ao Hipay Comprafácil em cada chamada ao webservice. Este parâmetro será obrigatório num futuro próximo, pelo que se recomenda que seja recolhido e fornecido ao Hipay Comprafácil desde já. IDUserBackoffice: quando uma referência é gerada, esta pode ser associada a um utilizador de backoffice no sistema Hipay Comprafácil. Para isso o seu identificador deve ser fornecido. Este parâmetro pode ser ignorado passando o valor -1. Obrigatório. timelimitdays: limite de tempo em dias para o cliente final pagar a referência. Podem ser 3, 30 ou 90 dias. Para a entidade sem limite de tempo para pagamento este valor é ignorado passando -1. Para a entidade com tempo limite para pagamento se este valor for -1, então a validade das referências é a que estiver definida na conta do parceiro. sendemailbuyer: especifica se um e-mail é enviado ao cliente final (esta funcionalidade tem de ser previamente activada para a conta do parceiro). Este e-mail é enviado pelo Hipay Comprafácil ao cliente final em nome do parceiro que gerou a referência informando que o parceiro gerou uma nova referência para pagamento. Parâmetros de saída reference / entity / amountout: detalhes de pagamento utilizados pelo cliente final para pagar num ATM ou home banking do seu banco. error: em caso de erro na geração da referência, este parâmetro irá conter uma descrição do sucedido. Valor devolvido 6
true se a referência foi gerada com sucesso, false caso contrário Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getreferencemb getreferencemb2 Obtém uma nova referência MULTIBANCO para pagamento especificando um identificador de produto armazenado no Hipay Comprafácil. Este método calcula internamente o montante a pagar de acordo com a quantidade especificada e devolve o valor no parâmetro amountout. O parâmetro timelimitdays especifica o número total de dias em que a referência é pagável. Para a entidade sem data limite para pagamento este valor é ignorado. Parâmetros de entrada origin: (mesmo que em getreferencemb) productid: identificador do produto armazenado no Hipay Comprafácil; este produto tem um preço unitário definido no Hipay Comprafácil. Obrigatório. username/password: (mesmo que em getreferencemb) quantity: número de items. Obrigatório. additionalinfo: (mesmo que em getreferencemb) name: (mesmo que em getreferencemb) address: (mesmo que em getreferencemb) postcode: (mesmo que em getreferencemb) city: (mesmo que em getreferencemb) NIC: (mesmo que em getreferencemb) externalreference: (mesmo que em getreferencemb) contactphone: (mesmo que em getreferencemb) email: (mesmo que em getreferencemb) IDUserBackoffice: (mesmo que em getreferencemb) timelimitdays: (mesmo que em getreferencemb) sendemailbuyer: (mesmo que em getreferencemb) parâmetros de saída reference / entity / amountout: detalhes de pagamento utilizados pelo cliente final para pagar num ATM ou home banking do seu banco. 7
error: em caso de erro na geração da referência, este parâmetro irá conter uma descrição do sucedido. Valor devolvido true se a referência foi gerada com sucesso, false caso contrário Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getreferencemb2 getreferenceps Obtém uma nova referência PayShop especificando o montante. Parâmetros de entrada origin: (mesmo que em getreferencemb) username/password: (mesmo que em getreferencemb) amount: (mesmo que em getreferencemb) additionalinfo: (mesmo que em getreferencemb) name: (mesmo que em getreferencemb) address: (mesmo que em getreferencemb) postcode: (mesmo que em getreferencemb). city: (mesmo que em getreferencemb) NIC: (mesmo que em getreferencemb) externalreference: (mesmo que em getreferencemb). contactphone: (mesmo que em getreferencemb) email: (mesmo que em getreferencemb) IDUserBackoffice: (mesmo que em getreferencemb) sendemailbuyer: (mesmo que em getreferencemb) Parâmetros de saída reference: referência para o cliente final pagar num agente PaysShop. paymentdeadline: data limite para pagamento da referência amountout: montante (em euros) utilizado para o cálculo da referência error: em caso de erro na geração da referência, este parâmetro irá conter uma descrição do sucedido. 8
Valor devolvido true se a referência foi gerada com sucesso, false caso contrário. Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getreferenceps getreferenceps2 Obtém uma nova referência PayShop para pagamento especificando um identificador de um produto armazenado no Hipay Comprafácil. Este método calcula internamente o montante a pagar de acordo com a quantidade especificada e devolve o valor no parâmetro amountout. origin: (mesmo que em getreferencemb) productid: (mesmo que em getreferencemb2) username/password: (mesmo que em getreferencemb) quantity: (mesmo que em getreferencemb2) additionalinfo: (mesmo que em getreferencemb) name: (mesmo que em getreferencemb) address: (mesmo que em getreferencemb) postcode: (mesmo que em getreferencemb) city: (mesmo que em getreferencemb) NIC: (mesmo que em getreferencemb) externalreference: (mesmo que em getreferencemb) contactphone: (mesmo que em getreferencemb) email: (mesmo que em getreferencemb) IDUserBackoffice: (mesmo que em getreferencemb) timelimitdays: (mesmo que em getreferencemb) sendemailbuyer: (mesmo que em getreferencemb) output parameters reference: referência para o cliente final pagar num agente PaysShop. paymentdeadline: data limite para pagamento da referência amountout: montante (em euros) utilizado para o cálculo da referência 9
error: em caso de erro na geração da referência, este parâmetro irá conter uma descrição do sucedido. Valor devolvido true se a referência foi gerada com sucesso, false caso contrário. Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getreferenceps2 3.2.2. Métodos para obter informação sobre referências O sistema Hipay Comprafácil permite obter informação sobre as referências armazenadas no sistema. É importante referir que estes métodos não devem ser usados como método principal para o parceiro obter informação de pagamento das referências. Para isso, um método passivo deve ser usado e que consiste no fornecimento de um URL que o Hipay Comprafácil irá chamar (descrito em baixo). Estes métodos em casos onde sejam absolutamente necessários. getinfo Obtém informação sobre referências. Devolve a lista de referências e respectivos IDs. Como parâmetro de entrada, se for especificado type=p então são devolvidas listas de referências pagas entre as datas especificadas; com type=r são devolvidas listas de referências criadas (e não necessariamente pagas ainda) entre as datas especificadas. O método devolve true/false e o parâmetro de saída error devolve uma mensagem de erro. As listas são devolvidas nos parâmetros referenceslist e IDsList (importante: as datas são no formado dd-mm-aaaa hh:mm:ss Ex: 24-02-2012 14:35:22) Parâmetros de entrada username/password: dados de acesso ao webservice. Obrigatório. datestartstr: data de início. Obrigatório. dataendstr: data final. Obrigatório. type: type = P devolve listas de referências pagas entre as datas especificadas; type=r devolve listas de referências criadas (e não necessariamente pagas ainda) entre as datas especificadas. Obrigatório. Parâmetros de saída referenceslist: lista de referências. IDsList: lista de IDs das referências devolvidas em referenceslist. error: em caso de erro no processamento, este parâmetro irá conter uma descrição do sucedido. Valor devolvido true / false 10
Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getinfo getinforeference Obtém informação sobre uma referência. Parametros de entrada reference: a referência para a qual se quer obter informação. Obrigatório. username/password: dados de acesso ao webservice. Obrigatório. Parâmetros de saída paid: true se a referência foi paga pelo menos uma vez, false caso contrário. status: estado de processamento. Pode ser: "Recebida", "Aceite", "Recusada" ou "Enviada". Se esta funcionalidade não é usada, este valor pode ser ignorado. lastpaymentdate: dará do último pagamento. totalpayments: número total de pagamentos desta referência. error: em caso de erro no processamento, este parâmetro irá conter uma descrição do sucedido. Valor devolvido true / false Pode ser encontrada mais informação sobre este método neste endereço: https://hm.comprafacil.pt/sibsclick/webservice/comprafacilws.asmx?op=getinforeference 4. Notificação de pagamento Quanto uma referência é paga, o Hipay Comprafácil tem duas formas de notificar o parceiro desta ocorrência: Através do envio de um e-mail para um endereço de e-mail especificado na conta do parceiro; Através da chamada de um URL definido pelo parceiro. 4.1 Chamada de URL do parceiro Se esta opção está activa para a conta do parceiro, é possível especificar um URL para ser chamado quando a referência é paga. 11
Este URL pode ser definido como fixo na conta do parceiro (para uso quando a referência é pedida por SMS) ou no parâmetro origin quando é utilizado um método dos webservices para gerar a referência. Em ambos os casos o URL apenas será chamado se esta opção está activa na conta do parceiro (feito a pedido deste) e se o mesmo é um URL válido. Se o URL é especificado na conta do parceiro (URL fixo), então a chamada é feita com os seguintes parâmetros: origem (parâmetro origin do método do webservice), ref (a referência) e paycount (número de vezes que a referência foi paga. Por exemplo, se este URL foi especificado na conta do parceiro: http://www.yoursite.com/page.aspx então o URL a ser chamado sera deste tipo: http://www.yoursite.com/page.aspx?origem=[origin]&paycount=1&ref=123+456+789 Se o parâmetro origin for preenchido ao ser gerada uma referência e se for reconhecido como um URL válido, então este valor terá prioridade na chamada (o URL especificado na conta do parceiro será ignorado). Desta forma, se for especificado o parâmetro origin (quando a referência é criada, na chamada ao método do webservice) este URL: http://www.yoursite.com/page.aspx?id=123456 então um URL deste tipo será chamado: http://www.yoursite.com/page.aspx?id=123456&paycount=1&ref=123+456+789 Os parâmetros ref e paycount são adicionados ao URL especificados no parâmetro origin quando a chamada ao método do webservice foi feita. O URL do parceiro não tem de devolver nenhum valor específico. O sucesso da chamada é determinado pelo valor do código HTTP obtido. No caso da chamada devolver OK (código http 200) então o sistema Hipay Comprafácil considera que a chamada foi feita com sucesso. Se o sistema Hipay Comprafácil obtiver outro valor que não o 200 (HTTP 500, HTTP 400, etc.) então a chamada é considerada como não sendo bem sucedida e tentará a chamada novamente. Durante 6 horas são feitas novas tentativas. Passado este tempo assume-se que o erro é permanente e o parceiro é notificado desta situação através do envio de um e-mail de aviso. 5. Exemplos de código Estão disponíveis alguns exemplos de código para download. Estes exemplos são muito básicos e apenas demonstram como chamar um método do webservice. O técnico responsável pela implementação pode usar estes exemplos como base do seu projecto. ASP.NET C# https://hm.comprafacil.pt/download/asp.net.zip 12
VB https://hm.comprafacil.pt/download/asp.net.vb.zip PHP Este exemplo usa a biblioteca standard de SOAP do PHP. https://hm.comprafacil.pt/download/php.zip Este exemplo usa uma biblioteca de SOAP alternativa para os casos em que a biblioteca standard não está disponível. https://hm.comprafacil.pt/download/php_nusoap.zip PHP (PayShop) Este exemplo usa a biblioteca standard de SOAP do PHP. https://hm.comprafacil.pt/download/php_ps.zip Este exemplo usa uma biblioteca de SOAP alternativa para os casos em que a biblioteca standard não está disponível. https://hm.comprafacil.pt/download/php_nusoap_ps.zip JAVA Para acesso a este exemplo o parceiro deve contactar a Hipay através de portugal@hipay.com Classic ASP Para acesso a este exemplo o parceiro deve contactar a Hipay através de portugal@hipay.com 6. Informação adicional Para qualquer informação técnica adicional por favor contactar: José Novais Telemóvel: + 351 91 565 35 31 E-mail: jose.novais@webeffect.pt Para passwords de teste ou uso do sistema, ou qualquer outra questão, por favor contacte a Hipay. Tel.: +351 213 822 199 portugal@hipay.com http://www.hipaycomprafacil.com 13