IFMB

MANUAL TCNICO
Real-Time
verso 1.0

Ifthen Software
Rua S. Jos, 757
4535- 404 Sta Maria Lamas

tel +351 227 459 324

fax +351 227 459 006

info@ifthensoftware.com
suporte@ifthensoftware.com
www.ifthensoftware.com
IFMB Manual Tcnico

ndice

1. Gerao das referncias multibanco..................................................................................... 3

a) Atravs do nosso back-office ............................................................................................ 3
b) Atravs do nosso aplicativo off-line ................................................................................... 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 ...................................................................................... 11
2.6. Back-Office: Testar Referncias ..................................................................................... 12
2.7. Back-Office: Alterar palavra-passe.................................................................................. 12
3. O algoritmo de gerao das referncias ............................................................................. 13
4. Notificaes dos Pagamentos ............................................................................................. 16
4.1. WebService ..................................................................................................................... 16
4.2. Chamada de URL Call Back ...................................................................................... 18

IFMB 2
IFMB Manual Tcnico

1. Gerao das referncias multibanco

Aps a adeso ao nosso servio de pagamentos IFMB, receber da Ifthen:

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.ifthensoftware.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 Ifthen 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.ifthensoftware.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 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 3
IFMB Manual Tcnico

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.

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;
O cliente poder pagar a mesma referncia mais do que uma vez;
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 Ifthen, 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, 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

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.ifthensoftware.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.

IFMB 4
IFMB Manual Tcnico

Por outro lado, pelo mtodo anterior pode criar referncias em qualquer
computador ou outro dispositivo com ligao internet, sem necessidade de
instalar qualquer software.

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 Ifthen 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 OsCommerce, Joomla Virtuemart, PrestaShop,
Magento, ZenCart, OpenCart, TomatoCart, WHMCS, WordPress 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.

IFMB 5
IFMB Manual Tcnico

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.ifthensoftware.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.

Verifique nomeadamente: se est a utilizar a entidade e sub-entidade que a Ifthen

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 seu site. Ns fornecemos exemplos de
implementao e damos-lhe toda a informao e apoio tcnico necessrio.

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 Ifthen 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, em folhas de clculo (Excel), formulrios de
inscries em eventos, etc.

Contacte-nos para avaliarmos a melhor soluo para cada caso.

IFMB 6
IFMB Manual Tcnico

2. Manual do Back-Office

O Back-Office na internet do IFMB da IFTHEN em www.ifthensoftware.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 Ifthen aps a assinatura do contrato.

Para se registar proceda do seguinte modo:

1. Entre no site www.ifthensoftware.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 7
IFMB Manual Tcnico

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.ifthensoftware.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.

IFMB 8
IFMB Manual Tcnico

Menu Multibancos

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 Ifthen.

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.

2 3

Exemplo do ecr de consulta de pagamentos

O quadro de pagamentos constituda pelas seguintes colunas (campos rea ): 1

Processamento: Data de processamento do pagamento;

Pagamento: Data/Hora real do pagamento;
Terminal: Terminal multibanco utilizado no pagamento (ou Homebanking);

IFMB 9
IFMB Manual Tcnico

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;
Tarifa: Tarifa cobrada pela Ifthen;
Valor Lquido: Valor pago deduzido da tarifa;

Na parte superior da pgina (rea 2 ), 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 ).3

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 4 ). Note que estas
pesquisas esto tambm condicionadas pelos filtros definidos na rea 3 . 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 ).
5

2.4. Back-Office: Consulta de Faturao

Selecionando o menu Multibancos>Consulta de Faturao tem acesso s faturas/recibo

emitidas mensalmente pela Ifthen relativas aos custos deste servio.

IFMB 10
IFMB Manual Tcnico

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.

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.

IFMB 11
IFMB Manual Tcnico

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
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 12
IFMB Manual Tcnico

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:

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.

* * * 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 Ifthen 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 IFTHEN.

Valor
Valor a pagar com no mximo 8 dgitos (excluindo o separador decimal) : XXX XXX,XX

IFMB 13
IFMB Manual Tcnico

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.

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 IFTHEN.

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 +

IFMB 14
IFMB Manual Tcnico

45 x 7 dgito +
53 x 8 dgito +
15 x 9 dgito +
50 x 10 dgito +
5x 11 dgito +
49 x 12 dgito +
34 x 13 dgito +
81 x 14 dgito +
76 x 15 dgito +
27 x 16 dgito +
90 x 17 dgito +
9x 18 dgito +
30 x 19 dgito +
3x 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 Ifthen 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.ifthensoftware.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 IFTHEN.

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.ifthensoftware.com/downloads/ifmb/Exemplos_Implementacao.zip

IFMB 15
IFMB Manual Tcnico

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.ifthensoftware.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);
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.ifthensoftware.com/IfmbWS/IfmbWS.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 IFTHEN na assinatura do contrato.

Obrigatrio.
Entidade: Entidade (5 dgitos) fornecida pela IFTHEN na assinatura do contrato.
Obrigatrio.
Subentidade: Sub-Entidade (3 dgitos) fornecida pela IFTHEN na assinatura do
contrato. Obrigatrio.

IFMB 16
IFMB Manual Tcnico

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.

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.ifthensoftware.com/IfmbWS/IfmbWS.asmx/getPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=&valor=

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.ifthensoftware.com/IfmbWS/IfmbWS.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=

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.

IFMB 17
IFMB Manual Tcnico

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.ifthensoftware.com/IfmbWS/IfmbWS.asmx/getPayments?chavebackoffice=
0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=
&dtHrFim=&referencia=999123420&valor=10.25

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.

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.

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 Ifthen por e-mail.

IFMB 18
IFMB Manual Tcnico

Devero tambm definir e enviar Ifthen 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 Ifthen considera que a chamada
foi efetuada com sucesso, caso devolva um cdigo diferente (HTTP 400, 500 ou outro) ento a
Ifthen 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.

IFMB 19