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
[email protected].
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 [email protected]
Classic ASP
Para acesso a este exemplo o parceiro deve contactar a Hipay através de [email protected]
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: [email protected]
Para passwords de teste ou uso do sistema, ou qualquer outra questão, por favor contacte a
Hipay.
Tel.: +351 213 822 199
[email protected]
http://www.hipaycomprafacil.com
13