Download - Manual Ifmb
-
IFMB
MANUAL DO UTILIZADOR E MANUAL TCNICO
verso 1.2
IfthenPay, Lda Instituio de Pagamento Autorizada e
Supervisionada pelo Banco de Portugal
Rua S. Jos, 771
4535- 404 Sta Maria Lamas
Contribuinte n: 510 450 024
tel +351 227 459 324
fax +351 227 459 006
www.ifthenpay.com
-
IFMB 2
ndice
1. Gerao das referncias multibanco ................................................................................ 3
a) Atravs do nosso back-office ........................................................................................ 3
b) Atravs do nosso aplicativo off-line (calculadora) ...................................................... 4
c) No seu site ou loja on-line .............................................................................................. 5
d) No seu software de gesto ............................................................................................. 6
e) Outras formas de gerar referncias multibanco .......................................................... 6
2. Manual do Back-Office ........................................................................................................ 7
2.1. Registo no Back-Office ...................................................................................................... 7
2.2. Entrar no Back-Office (Login) ............................................................................................ 8
2.3. Back-Office: Consulta de Pagamentos ............................................................................. 9
2.4. Back-Office: Consulta de Faturao ............................................................................... 10
2.5. Back-Office: Gerar Referncias ...................................................................................... 10
2.6. Back-Office: Testar Referncias ..................................................................................... 11
2.7. Back-Office: Alterar palavra-passe .................................................................................. 12
3. O algoritmo de gerao das referncias ......................................................................... 13
4. Notificaes dos Pagamentos ......................................................................................... 15
4.1. WebService ..................................................................................................................... 16
4.2. Chamada de URL Call Back ...................................................................................... 19
-
IFMB 3
1. Gerao das referncias multibanco
Aps a adeso ao nosso servio de pagamentos IFMB, receber da IfthenPay:
Entidade: Entidade multibanco (5 dgitos) que dever utilizar na gerao das
referncias;
Sub-Entidade: Sub-Entidade (3 dgitos) que dever utilizar na gerao das referncias;
Chave de acesso ao Back-Office: Chave no formato 0000-0000-0000-0000 que
dever utilizar para se registar no nosso site em www.ifthenpay.com;
* * * NOTA IMPORTANTE * * *
Em todos os exemplos neste manual iremos utilizar para fins demonstrativos a Entidade 11604
e a Sub-Entidade 999. Em casos reais, no dever utilizar esta entidade e sub-entidade mas
sim a entidade e sub-entidade que vos foi atribuda pela IfthenPay aquando da adeso ao
servio!
Existem vrias formas alternativas de gerarem as referncias multibanco, consoante as
necessidades:
a) Atravs do nosso back-office
Depois de se registar no nosso site em www.ifthenpay.com com a chave de acesso
ao back-office que lhe foi fornecida aquando da adeso ao servio, poder desde
logo gerar referncias multibanco (ver procedimento detalhado no ponto 2 deste
manual).
Como proceder:
1. Faa Login no nosso site (previamente dever ter feito o registo);
2. Aceda ao menu Multibancos>Gerar Referncias;
3. Escolha a sua entidade e sub-entidade;
4. Indique um ID e o valor a pagar. O ID um nmero entre 0 e 9999 que far
parte integrante da referncia e lhe permitir, mais tarde, identificar o
pagamento. Habitualmente utiliza-se o n da encomenda, n da fatura, n do
cliente, n do processo, etc;
5. Clique no boto Gerar Referncia
Dever disponibilizar ao seu cliente a seguinte informao para que ele possa
efetuar o pagamento (Entidade, Referncia e Valor):
-
IFMB 4
Notas:
No basta enviar ao cliente a referncia. Ter sempre que lhe disponibilizar
a entidade, referncia e valor a pagar;
Os 9 dgitos da referncia multibanco so sempre construdos da seguinte
forma: os 3 primeiros dgitos so obrigatoriamente os 3 dgitos da sub-
entidade (999 neste caso); os 4 dgitos seguintes so o ID (1234 neste
caso); os 2 ltimos so os check-digits calculados (90 neste caso);
As referncias criadas apenas podem ser pagas pelo montante para o qual
foram geradas. Caso o cliente tente pagar outro valor no conseguir. Para
isso, ter que gerar uma nova referncia para o montante pretendido e
envi-la ao cliente;
Algumas das nossa entidades permitem o pagamento da mesma
referncia um n indeterminado de vezes, outras no. Caso essa situao
seja importante no seu caso informe-se com a IfthenPay do tipo de
entidade que melhor satisfaz as suas necessidades;
Pode gerar quantas referncias quiser, o n de vezes que quiser. Se voltar
a colocar o mesmo ID e o mesmo valor, a referncia que ser gerada ser
sempre a mesma. Quando cria referncias, as mesmas no ficam
guardadas nem so enviadas para ningum (nem para a IfthenPay, nem
para a SIBS). Apenas quando forem pagas entram no sistema;
Caso d a mesma referncia (com o mesmo ID e o mesmo montante) a
vrios clientes, caso a entidade permita mltiplos pagamentos da mesma
referncia, todos eles conseguiro pagar, mas depois no ter forma direta
de identificar quem pagou o qu. Por isso se aconselha que utilize sempre
IDs diferentes e que lhe permitam depois identificar quem pagou o qu.
b) Atravs do nosso aplicativo off-line (calculadora)
Poder tambm gerar as referncias multibanco atravs de um aplicativo que
disponibilizamos para download no nosso site e o qual poder instalar no seu
computador (https://www.ifthenpay.com/downloads/ifmb/ifmultibanco.zip).
O processo de criar as referncias por este mtodo idntico ao anterior e d
origem a exatamente as mesmas referncias. A diferena que o mtodo anterior
obriga-o a ter uma ligao internet para entrar no back office, enquanto que com
este aplicativo pode faz-lo mesmo sem estar ligado internet.
Por outro lado, pelo mtodo anterior pode criar referncias em qualquer
computador ou outro dispositivo com ligao internet, sem necessidade de
instalar qualquer software.
Pagamento por Multibanco
ou Homebanking
Entidade: 11604
Referncia: 999 123 490
Valor: 25,86
O talo emitido pela caixa automtico faz prova de
pagamento. Conserve-o.
-
IFMB 5
Depois de fazer a instalao do aplicativo (basta fazer o download do mesmo,
descompact-lo e execut-lo), poder desde logo gerar referncias multibanco.
Como proceder:
1. A primeira vez que entrar no aplicativo dever ir aos parmetros introduzir a
Entidade e Sub-Entidade que a IfthenPay lhe forneceu aquando da adeso ao
servio (certifique-se que colocou os dados corretamente);
2. Aceda ao Separador Criao de Referncias e indique o ID e o Valor a
Pagar. O ID um nmero entre 0 e 9999 que far parte integrante da
referncia e lhe permitir mais tarde identificar o pagamento. Habitualmente
utiliza-se o n da encomenda, n da fatura, n do cliente, n do processo, etc;
3. Clique no boto Criar Referncia.
c) No seu site ou loja on-line
As referncias multibanco podero tambm ser geradas automaticamente pelo seu
site ou loja on-line.
Neste caso, ter que parametrizar/desenvolver no seu site esta modalidade de
pagamento. Para o ajudar neste sentido, desenvolvemos alguns exemplos para
algumas das plataformas de comrcio eletrnico mais utilizadas e respetivos
manuais de instalao (como o PrestaShop, OsCommerce, Joomla Virtuemart,
Magento, ZenCart, OpenCart, TomatoCart, WHMCS, Magento, Drupal 7.x
(Commerce e Ubercart), Wordpress (Classipress e WP e-Commerce,
WooCommerce), EPages, Amen, WebNode, Ecwid, SHOPIFY, Cubecart e outras),
bem como a descrio detalhada da funo de clculo das referncias e exemplos
em vrias linguagens de programao. Dever fazer chegar esta informao ao
seu Web Developer.
Pode fazer o download dos exemplos, mdulos para as principais plataformas de
e-commerce e da descrio tcnica detalhada da funo de clculo das referncias
neste link:
https://www.ifthenpay.com/downloads/ifmb/Exemplos_Implementacao.zip
Recomendamos que antes de colocar esta funcionalidade disponvel aos seus
clientes, teste e verifique se as referncias esto a ser corretamente criadas.
-
IFMB 6
Verifique nomeadamente: se est a utilizar a entidade e sub-entidade que a
IfthenPay lhe disponibilizou aquando da adeso ao servio; se as referncias esto
corretamente calculadas, utilizando a opo de Testar Referncias do nosso
back-office ou do aplicativo que disponibilizamos; se o ID (habitualmente o n da
encomenda) est a ser corretamente colocado na referncia.
Caso o seu web site no tenha sido desenvolvido em nenhuma das plataformas
para as quais disponibilizamos o mdulo, verifique com o seu Web Developer a
possibilidade de integrar o nosso servio no carrinho de compras do seu site. Ns
fornecemos exemplos de implementao e damos-lhe toda a informao e apoio
tcnico necessrio.
Se o seu web site no tem carrinho de compras e pretende mesmo assim
disponibilizar aos utilizadores a possibilidade de efectuar compras e pagamentos,
contacte-nos e solicite-nos informaes acerca do Carrinho de Compras Virtual
da IfthenPay. O carrinho de compras virtual permite-lhe efectuar vendas atravs
de um simples link que poder colocar no seu web site, e-mails, newsletters,
pgina do facebook, etc.
d) No seu software de gesto
As referncias multibanco podero tambm ser geradas automaticamente pela
maior parte dos softwares de gesto existentes no mercado.
Caso o seu software de faturao possa ser configurado para incluir as nossas
referncias multibanco, as mesmas podero ser impressas nos documentos,
automaticamente, sempre que os imprimir.
A configurao do nosso servio no seu software de faturao pode ser efetuada
de vrias formas, sendo que na sua forma mais simples pode passar por uma
simples configurao do report da fatura, onde se inclui o cdigo necessrio para a
gerao das referncias multibanco em off-line. Nesse caso, apenas se faz uma
atualizao ao report, no havendo necessidade de qualquer alterao ao software
ou base de dados.
Contacte a IfthenPay ou a empresa responsvel pelo seu software de gesto para
verificar a possibilidade dessa configurao.
Dispem tambm de um exemplo em Crystal Reports no nosso link tcnico.
e) Outras formas de gerar referncias multibanco
Existem ainda outras possibilidades para a gerao das nossas referncias
multibanco, como por exemplo:
- Plataforma de donativos (boto Doar);
- Plataforma de inscrio em eventos;
- Plataforma Carinho de Compras Virtual para integrao com facebook,
newsletters, e-mails, sites institucionais (que no tm carrinho de compras), etc;
- Folhas de clculo (Excel).
Contacte-nos para avaliarmos a melhor soluo para cada caso.
-
IFMB 7
2. Manual do Back-Office
O Back-Office na internet do IFMB da IFTHENPAY em www.ifthenpay.com permite:
A consulta on-line em tempo real (real-time) de todos os pagamentos efetuados;
A consulta/impresso das faturas mensais das comisses do servio;
A gerao de referncias multibanco;
O teste de referncias multibanco;
2.1. Registo no Back-Office
Para aceder ao back-office ter primeiro que se registar, utilizando para isso a chave de
acesso ao back-office que lhe foi disponibilizada pela IfthenPay aps a assinatura do
contrato.
Para se registar proceda do seguinte modo:
1. Entre no site www.ifthenpay.com;
2. Clique em Registar no canto superior direito da pgina;
3. Preencha os dados pedidos:
Utilizador: escolha o nome do utilizador pretendido (sensvel a
maisculas/minsculas);
Palavra passe: escolha a senha de acesso pretendida (sensvel a
maisculas/minsculas);
E-mail: o seu e-mail;
Chave: a chave que lhe fornecemos e que dar acesso aos movimentos da
sua Entidade/Sub-Entidade;
4. Clique no boto Criar Utilizador
Exemplo de um registo de utilizador
Pode repetir o processo e efetuar mais do que um registo para utilizadores diferentes.
-
IFMB 8
2.2. Entrar no Back-Office (Login)
Aps efetuar o registo pode ento entrar no back-office em qualquer computador ou dispositivo
que tenha acesso internet.
Para entrar no back-office (login) proceda do seguinte modo:
1. Entre no site www.ifthenpay.com;
2. Clique em Login (no canto superior direito da pgina);
3. Coloque o seu utilizador e palavra passe (pode memorizar para no lhe serem pedidas
novamente. Ateno s maisculas/minsculas.)
4. Clique no boto Iniciar Sesso
Exemplo da janela de login
Tem tambm disponveis as opes:
Repor palavra-passe: utilize esta opo se se esqueceu da sua palavra passe. Ser-
lhe- gerada uma nova palavra-passe aleatria que ser enviada para o e-mail que
indicou no registo. Aps a receo do e-mail poder utilizar a opo seguinte para
alterar a palavra-passe para uma da sua preferncia;
Alterar palavra-passe: utilize esta opo para alterar a sua palavra-passe;
Aps efetuado o Login, surgir o menu Multibancos onde poder aceder s vrias
funcionalidades do servio.
Menu Multibancos
-
IFMB 9
Caso no lhe aparea o menu Multibancos as causas provveis so:
Ainda no efetuou o Login (caso tenha efetuado o Login dever aparecer-lhe no
canto superior direito da pgina o seu nome de utilizador);
Registou-se no site sem colocar a chave de acesso ao back office. Neste caso ter
que fazer um novo registo, com um novo nome de utilizador, indicando ento no
registo a sua chave de acesso ao back-office fornecida pela IfthenPay.
2.3. Back-Office: Consulta de Pagamentos
Selecionando o menu Multibancos>Consulta de Pagamentos tem acesso em real-time aos
pagamentos efetuados por referncia multibanco.
Exemplo do ecr de consulta de pagamentos
O quadro de pagamentos constituda pelas seguintes colunas (campos rea ):
Processamento: Data de processamento do pagamento;
Pagamento: Data/Hora real do pagamento;
Terminal: Terminal multibanco utilizado no pagamento (ou Homebanking);
Referncia MB: Referncia multibanco paga;
ID: ID (habitualmente o n da encomenda ou do cliente). Est embutido na referncia
tambm (4 a 7 caracteres);
Valor Pago: Valor pago pelo cliente;
1
2 3
5
1
4
-
IFMB 10
Tarifa: Tarifa cobrada pela IfthenPay;
Valor Lquido: Valor pago deduzido da tarifa;
Na parte superior da pgina (rea ), pode definir os filtros pretendidos para a informao a
apresentar. Pode nomeadamente filtrar por entidade e sub-entidade (no caso de ter mais do
que uma), por ano e ms de processamento. Sempre que altere os filtros ou sempre que quiser
atualizar o quadro de pagamentos ter que clicar no boto Atualizar (rea ).
Pode ainda pesquisar (filtrar) no quadro de pagamentos por qualquer dos campos,
preenchendo o valor a pesquisar nas caixas de texto de cada coluna (rea ). Note que estas
pesquisas esto tambm condicionadas pelos filtros definidos na rea . Ou seja, se
pretender saber se uma determinada referncia foi paga numa qualquer data do passado, ter
que configurar o filtro do ano e do ms para o perodo no qual deseja pesquisar (ou colocar
Todos para pesquisar em todos os anos/meses).
Pode tambm ordenar o quadro pelo campo que quiser, simplesmente clicando no ttulo das
colunas a ordenar.
Existe ainda a possibilidade de agrupar o quadro por um determinado campo, arrastando a
coluna respetiva para a rea de agrupamento. Por exemplo se arrastar a coluna da data de
processamento, passa a ter a informao do quadro agrupada por esse campo, sendo
inclusivamente apresentados sub-totais por esse campo.
Caso pretenda exportar a informao do quadro de pagamentos para Excel (XLS), PDF, RTF
ou CSV basta clicar no boto respetivo (na rea ).
2.4. Back-Office: Consulta de Faturao
Selecionando o menu Multibancos>Consulta de Faturao tem acesso s faturas/recibo
emitidas mensalmente pela IfthenPay relativas aos custos deste servio.
O quadro onde aparecem as faturas tem um funcionamento em tudo semelhante ao quadro
dos pagamentos descrito anteriormente.
2.5. Back-Office: Gerar Referncias
Selecionando o menu Multibancos>Gerar Referncias tem acesso rea de gerao de
referncias. Como descrito no ponto 1 deste manual, esta apenas uma das formas de gerar
referncias.
2
3
4
3
5
-
IFMB 11
Para gerar uma referncia proceda do seguinte modo:
1. Escolha a sua entidade e sub-entidade;
2. Indique um ID e o valor a pagar. O ID um nmero entre 0 e 9999 que far parte
integrante da referncia e lhe permitir mais tarde identificar o pagamento.
Habitualmente utiliza-se o n da encomenda, n da fatura, n do cliente, n do
processo, etc;
3. Clique no boto Gerar Referncia
Dever disponibilizar sempre ao seu cliente a Entidade, Referncia e Valor para ele poder
efetuar o pagamento.
2.6. Back-Office: Testar Referncias
Selecionando o menu Multibancos>Testar Referncias tem acesso rea de teste de
referncias.
No necessita de testar as referncias que gerou pelo mtodo anteriormente descrito. Esta
opo mais utilizadas para:
Caso um cliente o contacte a informar que no est a conseguir pagar uma
determinada referncia multibanco, pode utilizar esta opo para verificar se a mesma
-
IFMB 12
est correta (o cliente pode ter se enganado ao tomar nota da referncia ou estar a
trocar algum dgito);
Se fizer a implementao da gerao das referncias num site ou noutro software,
pode utilizar esta opo para validar se as referncias foram corretamente calculadas;
2.7. Back-Office: Alterar palavra-passe
Selecionando o menu Multibancos>Alterar palavra-passe tem acesso rea de alterao da
palavra-passe de acesso ao back office.
-
IFMB 13
3. O algoritmo de gerao das referncias
No caso de necessitarem, por algum motivo, de desenvolver o clculo das nossas referncias multibanco, deixamos aqui a explicao passo-a-passo do algoritmo de gerao das referncias. No sistema multibanco existem 3 conjuntos de dgitos utilizados pelo cliente para efetuar o pagamento: Entidade, Referncia e Valor.
Exemplo:
* * * NOTA IMPORTANTE * * *
Em todos os exemplos neste manual iremos utilizar para fins demonstrativos a Entidade 11604
e a Sub-Entidade 999. Em casos reais, no dever utilizar esta entidade e sub-entidade mas
sim a entidade e sub-entidade que vos foi atribuda pela IfthenPay aquando da adeso ao
servio!
Esta caixa deve ser impressa no documento de venda (usualmente no canto inferior esquerdo) ou, no caso do comrcio eletrnico, apresentada/impressa pelo browser e, preferencialmente, enviada tambm por e-mail nos detalhes da encomenda. A data limite de pagamento pode ser tambm apresentada, mas transparente para o sistema que aceitar pagamentos em qualquer data, mesmo posteriores. Os terminais multibanco aceitam tambm o pagamento da mesma referncia mais do que uma vez, pelo que o tratamento de pagamentos duplicados dever depois ser tratado administrativamente.
Entidade
A entidade ter sempre 5 dgitos e ser fornecida pela IFTHENPAY.
Valor
Valor a pagar com no mximo 8 dgitos (excluindo o separador decimal) : XXX XXX,XX
No caso de valores inteiros devem-se visualizar sempre as duas casa decimais (por exemplo 25,00 e no apenas 25). Pode-se incluir ou no o smbolo do Euro () frente do valor.
Pagamento por Multibanco
ou Homebanking
Entidade: 11604
Referncia: 999 123 490
Valor: 25,86
O talo emitido pela caixa automtico faz prova de
pagamento. Conserve-o.
-
IFMB 14
Referncia
A referncia composta sempre por 9 dgitos (em grupos de 3 facilita a visualizao) e no nosso sistema composta do seguinte modo: SSSDDDDCC Em que SSS: trs dgitos que identificam a sub-entidade (o vendedor). Este cdigo atribudo
pela IFTHENPAY. DDDD: ID - quatro dgitos que identificam o n do documento/encomenda a pagar ou o n
do v/ cliente (conforme prefiram associar o pagamento a um documento ou a um cliente). Este ID ter que ter obrigatoriamente 4 dgitos, pelo que caso o n do documento/encomenda ou o n do cliente tenha mais que 4 dgitos ter que utilizar apenas os 4 mais direita, caso tenha menos de 4 dgitos dever preencher os restantes com zeros esquerda.
CC: dois dgitos de controlo (check-digits). Serve para o terminal validar se a
informao est correta. Nota: Se o dgito de controlo s tiver um algarismo ter que format-lo para 2 algarismos colocando 0 (zero) esquerda.
No exemplo de cima: 11604 o cdigo da entidade; 999 o cdigo da sub-entidade; 1234 o ID - n do documento/encomenda a ser pago ou o nmero do v/ cliente; 90 so os dgitos de controlo; 25,86 o valor a pagar.
Clculo dos dgitos de controlo
a) Concatenar numa string: os 5 dgitos da entidade + os 3 dgitos da sub-entidade + 4 dgitos do ID + os 8 dgitos do valor (sem separador decimal e colocando zeros esquerda para dar 8 caracteres.
No nosso exemplo ficaria: 11604999123400002586
b) Fazer a seguinte operao:
Resultado1= 51 x 1 dgito + 73 x 2 dgito + 17 x 3 dgito + 89 x 4 dgito + 38 x 5 dgito + 62 x 6 dgito + 45 x 7 dgito + 53 x 8 dgito + 15 x 9 dgito + 50 x 10 dgito + 5 x 11 dgito + 49 x 12 dgito + 34 x 13 dgito + 81 x 14 dgito + 76 x 15 dgito + 27 x 16 dgito +
-
IFMB 15
90 x 17 dgito + 9 x 18 dgito + 30 x 19 dgito + 3 x 20 dgito No nosso exemplo: Resultado1 = 51x1 + 73x1 + 17x6 + 89x0 + 38x4 + 62x9 + 45x9 + 53x9 + 15x1 + 50x2 + 5x3 + 49x4 + 34x0 + 81x0 + 76x0 + 27x0 + 90x2 + 9x5 + 30x8 + 3x6 = 2627
c) Fazer a seguinte operao:
Resultado final = 98 (resultado1 mod 97) sendo mod o resto da diviso inteira No nosso exemplo: resultado final = 98 (2627 mod 97) = 98 8 = 90 Os dgitos de controlo seriam ento 90 Nota: caso o dgito de controlo s tivesse um algarismo (5 por exemplo) ter que format-lo para 2 algarismos colocando 0 (zero) esquerda (05 por exemplo).
Pagamento da Referncias
Imediatamente aps ser gerada a referncia, ela pode ser paga nos terminais Multibanco (ou HomeBanking, Telemultibanco ou MBSpot) na opo Pagamento de Compras/Servios (do mesmo modo que as faturas da eletricidade, gua, gs e telecomunicaes). Repare que no tem que fazer o envio das referncias que gerar para qualquer web servisse da IfthenPay ou da SIBS. Elas apenas tm que ser corretamente calculadas para poderem ser imediatamente pagas. Por outro lado, as referncias multibanco apenas podem ser pagas pelo valor para o qual foram geradas (o valor entra no clculo dos check-digits).
Teste das Referncias
Apesar da funo de clculo das referncias multibanco ser relativamente simples, teste o seu funcionamento para diferentes valores e IDs utilizando o nosso aplicativo de validao (disponvel em https://www.ifthenpay.com/downloads/ifmb/ifmultibanco.zip) ou o nosso back-office. Verifique tambm se est a utilizar a entidade e sub-entidade que lhe foi atribuda pela IFTHENPAY.
Exemplos de Implementao Pode fazer o download de exemplos de implementao deste algoritmo em vrias linguagens
de programao, bem como mdulos para as principais plataformas de e-commerce neste link:
https://www.ifthenpay.com/downloads/ifmb/Exemplos_Implementacao.zip
4. Notificaes dos Pagamentos
Existem diversas formas de aceder s notificaes dos pagamentos efetuados atravs do
nosso servio de pagamentos IFMB:
Atravs do back-office na nossa pgina na internet em www.ifthenpay.com, aps ter
efetuado o registo com a chave de acesso que lhe disponibilizamos, onde os
pagamentos so atualizados em real-time;
Atravs do e-mail instantneo (em real-time) enviado sempre que h um pagamento,
para os e-mails que definiu para esse fim (caso tenha esta opo ativa);
-
IFMB 16
Atravs do e-mail resumo dirio enviado diariamente com os pagamentos do dia
anterior;
Atravs dos extratos mensais com todos os pagamentos do ms;
Atravs da chamada ao nosso WebService;
Atravs da chamada de um URL definido por vs CallBack;
Os dois ltimos pontos so os indicados para quem pretenda fazer o tratamento automtico
dos pagamentos.
NOTA: A gerao das referncias multibanco no so efetuadas pelo nosso webservice, mas
apenas a notificao dos pagamentos
4.1. WebService
O webservice est disponvel no seguinte endereo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx
Os mtodos GetPayments, GetPaymentsJson e GetPaymentsXml devolvem os pagamentos
efectuados na entidade e sub-entidade indicada.
A nica diferena entre os trs mtodos o formato em que a informao devolvida. No
primeiro (GetPayments) devolvido no formato SOAP (1.1 e 1.2); No segundo
(GetPaymentsJson) devolvido em formato JSON; e no terceiro (GetPaymentsXml)
devolvido em formato puro XML.
Os parmetros a passar na chamada do mtodo so:
Chavebackoffice: Chave fornecida pela IFTHENPAY na assinatura do contrato.
Obrigatrio.
Entidade: Entidade (5 dgitos) fornecida pela IFTHENPAY na assinatura do contrato.
Obrigatrio.
Subentidade: Sub-Entidade (3 dgitos) fornecida pela IFTHENPAY na assinatura do
contrato. Obrigatrio.
dtHrInicio: Data/Hora inicial dos pagamentos pretendidos no formato dd-MM-yyyy
HH:mm:ss. Facultativo.
dtHrFim: Data/Hora final dos pagamentos pretendidos no formato dd-MM-yyyy
HH:mm:ss. Facultativo.
Referencia: Referncia multibanco (9 dgitos) sobre a qual se pretende saber a
informao do pagamento. Facultativo.
Valor: Valor em euros dos pagamentos que se pretende obter informao. Facultativo.
Sandbox: Devem indicar 1 ou 0 no caso de utilizarem ou no a plataforma de testes.
Obrigatrio.
-
IFMB 17
O mtodo pode ser chamado de vrias formas, conforme as necessidades:
a) Se pretende obter todos os pagamentos ainda no pedidos, independentemente da
data/hora em que ocorreram, dever passar apenas os parmetros chavebackoffice,
entidade, subentidade. Todos os outros devero ser deixados em branco.
Exemplo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx/GetPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=&valor=&sandbox=0
Devolve todos os pagamentos ainda no pedidos da entidade 11604, sub-entidade 999
com a chave de backoffice 0000-0000-0000-0000.
NOTA: Dever utilizar a sua chave, entidade e sub-entidade e no as indicadas neste
exemplo.
Sempre que voltar a executar este pedido, ser-lhe-o devolvidos apenas os novos
pagamentos que entretanto ocorram (caso ocorram).
b) Se pretende obter todos os pagamentos efetuados entre duas datas/horas dever
passar os parmetros chavebackoffice, entidade, subentidade, dtHrInicio,
dtHrFim. Todos os outros devero ser deixados em branco.
Exemplo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx/GetPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999
&dtHrInicio=23-05-2012 00:00:00&dtHrFim=23-05-2012
23:59:59&referencia=&valor=&sandbox=0
Devolve todos os pagamentos da entidade 11604, sub-entidade 999 com a chave de backoffice 0000-0000-0000-0000 efetuados no dia 23-05-2012 entre as 00h00m00s e as 23h59m59s. NOTA: Dever utilizar a sua chave, entidade e sub-entidade e no as indicadas neste exemplo. Neste caso, sero sempre devolvidos os pagamentos, quer tenham sido ou no
anteriormente lidos.
c) Se pretende apenas saber se uma determinada entidade/referncia/valor foi paga
dever passar os parmetros chavebackoffice, entidade, subentidade, referencia,
valor e opcionalmente a dtHrInicio e dtHrFim.
Exemplo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx/GetPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=999123420&valor=10.25&sandbox=0
Devolve, caso existam, todos os pagamentos efectuados na entidade, referncia e
valor indicados. Ter em ateno que podem existir mais do que um pagamento dessa
referncia. Podem tambm ser passados os parmetros da data/hora inicial e final.
-
IFMB 18
d) Se pretende saber se uma determinada entidade/referncia/valor foi paga fora do
ambiente de testes (sandbox) dever passar os parmetros chavebackoffice,
entidade, subentidade, referencia, valor, opcionalmente a dtHrInicio e dtHrFim e a
sandbox com o valor 0.
Exemplo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx/GetPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=999123420&valor=10.25&sandbox=0
Devolve, caso existam, todos os pagamentos efectuados na entidade, referncia e valor indicados fora do ambiente de testes. Ter em ateno que podem existir mais do que um pagamento dessa referncia. Podem tambm ser passados os parmetros da data/hora inicial e final.
e) Se pretende saber se uma determinada entidade/referncia/valor foi paga a partir do
ambiente de testes (sandbox) dever passar os parmetros chavebackoffice,
entidade, subentidade, referencia, valor, opcionalmente a dtHrInicio e dtHrFim e a
sandbox com o valor 1.
Exemplo:
https://www.ifthenpay.com/IfmbWS/WsIfmb.asmx/GetPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=999123420&valor=10.25&sandbox=1
Devolve, caso existam, todos os pagamentos efectuados na entidade, referncia e valor indicados no ambiente de testes. Ter em ateno que podem existir mais do que um pagamento dessa referncia. Podem tambm ser passados os parmetros da data/hora inicial e final.
Estes mtodos devolvem a seguinte informao para cada pagamento (1 ou mais):
Entidade entidade utilizada no pagamento (5 dgitos)
Referencia referncia multibanco paga (9 dgitos)
Valor valor pago em euros
Id id utilizado na gerao da referncia multibanco (4 dgitos)
DtHrPagamento data/hora do pagamento em formato dd-MM-yyyy HH:mm:ss
Processamento data de processamento yyyyMMdd1
Terminal terminal utilizado no pagamento
Tarifa tarifa do servio
ValorLiquido valor pago deduzido da tarifa
CodigoErro cdigo de erro
MensagemErro mensagem de erro
Cdigo Mensagem
0 Sucesso. 1 No existem pagamentos. 2 Erro nas Datas/Horas. 3 Chave invlida. 9 Erro desconhecido.
-
IFMB 19
4.2. Chamada de URL Call Back
Como alternativa ao WebService, podem utilizar o mtodo de Call Back para automatizar o
processamento dos pagamentos.
Neste caso, em vez de chamarem o nosso WebService periodicamente para verificar se
existem pagamentos, ns chamaremos um URL definido por vs sempre que ocorram
pagamentos.
Este URL dever ser previamente definido por vs e enviado IfthenPay por e-mail.
Devero tambm definir e enviar IfthenPay uma chave Anti-Phishing (uma string com o
mximo de 50 caracteres) que ser devolvida como parmetro quando chamarmos o URL,
para que possam verificar a autenticidade da mesma.
O URL indicado por vs dever incluir os parmetros que pretendem que sejam devolvidos
(entre parntesis retos []):
[CHAVE_ANTI_PHISHING] String definida previamente por vs para autenticarem a
resposta. Obrigatrio.;
[ENTIDADE] Entidade multibanco. Obrigatrio.;
[REFERENCIA] Referncia multibanco. Obrigatrio.;
[VALOR] Montante pago. Obrigatrio.;
[DATA_HORA_PAGAMENTO] Data/Hora de pagamento (devolve no formato dd-
MM-yyyy HH:mm:ss). Facultativo.;
[TERMINAL] Terminal utilizado no pagamento. Facultativo;
Exemplos de URL:
http://www.yoursite.com/callback.php?chave=[CHAVE_ANTI_PHISHING]&entidad
e=[ENTIDADE]&referencia=[REFERENCIA]&valor=[VALOR]&datahorapag=[DATA_HOR
A_PAGAMENTO]&terminal=[TERMINAL]
http://www.yoursite.com/callback.aspx?chave=[CHAVE_ANTI_PHISHING]&entida
de=[ENTIDADE]&referencia=[REFERENCIA]&valor=[VALOR]
O vosso URL no tem de devolver qualquer valor. O sucesso do nosso pedido determinado
pelo cdigo HTTP obtido: Caso devolva o cdigo HTTP 200 a IfthenPay considera que a
chamada foi efetuada com sucesso, caso devolva um cdigo diferente (HTTP 400, 500 ou
outro) ento a IfthenPay considera que a chamada no teve sucesso e tentar novamente mais
tarde (tentar 13 vezes sendo que as primeiras 8 sero de 5 em 5 minutos e as restantes de
hora em hora). Caso nessas 13 tentativas no obtenha a resposta OK, no voltar a tentar, e
enviar um e-mail a notificar o erro permanente.