IFMB

MANUAL TÉCNICO
Real-Time
versão 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 Técnico

Índice

1. Geração das referências multibanco...............................................................................3

a) Através do nosso back-office......................................................................................3
b) Através do nosso aplicativo off-line .............................................................................4
c) No seu site ou loja on-line ..........................................................................................5
d) No seu software de gestão.........................................................................................6
e) Outras formas de gerar referências multibanco ...........................................................6
2. Manual do Back-Office ..................................................................................................7
2.1. Registo no Back-Office ..............................................................................................7
2.2. Entrar no Back-Offic e (Login) .....................................................................................8
2.3. Back-Office: Consulta de Pagamentos ........................................................................9
2.4. Back-Office: Consulta de Faturação.......................................................................... 10
2.5. Back-Office: Gerar Referências ................................................................................ 11
2.6. Back-Office: Testar Referências ............................................................................... 12
2.7. Back-Office: Alterar palavra-passe............................................................................ 12
3. O algoritmo de geração das referências........................................................................ 13
4. Notificaç ões dos Pagamentos ...................................................................................... 16
4.1. WebService ............................................................................................................ 16
4.2. Chamada de URL – “Call Back”................................................................................ 19

IFMB 2
IFMB – Manual Técnico

1. Geração das referências multibanco

Após a adesão ao nosso serviço de pagamentos IFMB, receberá da Ifthen:

 Entidade: Entidade multibanco (5 dígitos) que deverá utilizar na geração das

referências;

 Sub-Entidade: Sub-Entidade (3 dígitos) que deverá utilizar na geração das referências;

 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, não deverá utilizar esta entidade e sub-entidade mas
sim a entidade e sub-entidade que vos foi atribuída pela Ifthen aquando da adesão ao serviço!

Existem várias formas alternativas de gerarem as referências multibanco, consoante as

necessidades:

a) Através 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 adesão ao serviço, poderá
desde logo gerar referências multibanco (ver ponto 2 deste manual).

Como proceder:

1. Faça “Login” no nosso site (previamente deverá ter feito o registo);

2. Aceda ao menu “Multibancos>Gerar Referências”;
3. Escolha a sua entidade e sub-entidade;
4. Indique um ID e o valor a pagar. O ID é um número entre 0 e 9999 que fará
parte integrante da referência 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 botão “Gerar Referência”

Deverá disponibilizar ao seu cliente a seguinte informação para que ele possa
efetuar o pagamento (Entidade, Referência e Valor):

IFMB 3
IFMB – Manual Técnico

Pagamento por Multibanco

ou Homebanking

Entidade: 11604

Referência: 999 123 490

Valor: 25,86 €

O talão emitido pela caixa automático faz prova de

pagamento. Conserve-o.

Notas:
 Não basta enviar ao cliente a referência. Terá sempre que lhe disponibilizar
a entidade, referência e valor a pagar;
 Os 9 dígitos da referência multibanco são sempre construídos da seguinte
forma: os 3 primeiros dígitos são obrigatoriamente os 3 dígitos da sub-
entidade (999 neste caso); os 4 dígitos seguintes são o ID (1234 neste
caso); os 2 últimos são os check-digits calculados (90 neste caso);
 As referências criadas apenas podem ser pagas pelo montante para o qual
foram geradas. Caso o cliente tente pagar outro valor não conseguirá. Para
isso, terá que gerar uma nova referência para o montante pretendido e
enviá-la ao cliente;
 O cliente poderá pagar a mesma referência mais do que uma vez;
 Pode gerar quantas referências quiser, o nº de vezes que quiser. Se voltar
a colocar o mesmo ID e o mesmo valor, a referência que será gerada será
sempre a mesma. Quando cria referências, as mesmas não ficam
guardadas nem são enviadas para ninguém (nem para a Ifthen, nem para
a SIBS). Apenas quando forem pagas entram no sistema;
 Caso dê a mesma referência (com o mesmo ID e o mesmo montante) a
vários clientes, todos eles conseguirão pagar, mas depois não 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) Através do nosso aplicativo off-line

Poderá também gerar as referências multibanco através 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 referências por este método é idêntico ao anterior e dá

origem a exatamente as mesmas referências. A diferença é que o método anterior
obriga-o a ter uma ligação à internet para entrar no back office, enquanto que com
este aplicativo pode fazê-lo mesmo sem estar ligado à internet.

IFMB 4
IFMB – Manual Técnico

Por outro lado, pelo método anterior pode criar referências em qualquer
computador ou outro dispositivo com ligação à internet, sem necessidade de
instalar qualquer software.

Depois de fazer a instalação do aplicativo (basta fazer o download do mesmo,

descompactá-lo e executá-lo), poderá desde logo gerar referências multibanco.

Como proceder:

1. A primeira vez que entrar no aplicativo deverá ir aos parâmetros introduzir a

Entidade e Sub-Entidade que a Ifthen lhe forneceu aquando da adesão ao
serviço (certifique-se que colocou os dados corretamente);
2. Aceda ao Separador “Criação de Referências” e indique o ID e o Valor a
Pagar. O ID é um número entre 0 e 9999 que fará parte integrante da
referência 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 botão “Criar Referência”.

c) No seu site ou loja on-line

As referências multibanco poderão também 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 comércio eletrónico mais utilizadas e respetivos
manuais de instalação (como o OsCommerce, Joomla Virtuemart, PrestaShop,
Magento, ZenCart, OpenCart, TomatoCart, WHMCS, WordPress e outras), bem
como a descrição detalhada da função de cálculo das referências e exemplos em
várias linguagens de programação. Deverá fazer chegar esta informação ao seu
Web Developer.

IFMB 5
IFMB – Manual Técnico

Pode fazer o download dos exemplos, módulos para as principais plataformas de

e-commerce e da descrição técnica detalhada da função de cálculo das referências
neste link:
https://www.ifthensoftware.com/downloads/ifmb/Exemplos_Implementacao.zip

Recomendamos que antes de colocar esta funcionalidade disponível aos seus

clientes, teste e verifique se as referências estão a ser corretamente criadas.

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

lhe disponibilizou aquando da adesão ao serviço; se as referências estão
corretamente calculadas, utilizando a opção de “Testar Referências” do nosso
back-office ou do aplicativo que disponibilizamos; se o ID (habitualmente o nº da
encomenda) está a ser corretamente colocado na referência.

Caso o seu web site não tenha sido desenvolvido em nenhuma das plataformas
para as quais disponibilizamos o módulo, verifique com o seu Web Developer a
possibilidade de integrar o nosso serviço no seu site. Nós fornecemos exemplos de
implementação e damos-lhe toda a informação e apoio técnico necessário.

d) No seu software de gestão

As referências multibanco poderão também ser geradas automaticamente pela

maior parte dos softwares de gestão existentes no mercado.

Caso o seu software de faturação possa ser configurado para incluir as nossas
referências multibanco, as mesmas poderão ser impressas nos documentos,
automaticamente, sempre que os imprimir.

A configuração do nosso serviço no seu software de faturação pode ser efetuada

de várias formas, sendo que na sua forma mais simples pode passar por uma
simples configuração do report da fatura, onde se inclui o código necessário para a
geração das referências multibanco em off-line. Nesse caso, apenas se faz uma
atualização ao report, não havendo necessidade de qualquer alteração ao software
ou à base de dados.

Contacte a Ifthen ou a empresa responsável pelo seu software de gestão para

verificar a possibilidade dessa configuração.

Dispõem também de um exemplo em Crystal Reports no nosso link técnico.

e) Outras formas de gerar referências multibanco

Existem ainda outras possibilidades para a geração das nossas referências

multibanco, como por exemplo, em folhas de cálculo (Excel), formulários de
inscrições em eventos, etc.

Contacte-nos para avaliarmos a melhor solução para cada caso.

IFMB 6
IFMB – Manual Técnico

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/impressão das faturas mensais das comissões do serviço;
 A geração de referências multibanco;
 O teste de referências 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 após 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 página;
3. Preencha os dados pedidos:
 Utilizador: escolha o nome do utilizador pretendido (sensível a
maiúsculas/minúsculas);
 Palavra passe: escolha a senha de acesso pretendida (sensível a
maiúsculas/minúsculas);
 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 botão “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 Técnico

2.2. Entrar no Back-Office (Login)

Após efetuar o registo pode então 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 página);
3. Coloque o seu utilizador e palavra passe (pode memorizar para não lhe serem pedidas
novamente. Atenção às maiúsculas/minúsculas.)
4. Clique no botão “Iniciar Sessão”

Exemplo da janela de login

Tem também disponíveis as opções:

 “Repor palavra-passe”: utilize esta opção se se esqueceu da sua palavra passe. Ser-
lhe-á gerada uma nova palavra-passe aleatória que será enviada para o e-mail que
indicou no registo. Após a receção do e-mail poderá utilizar a opção seguinte para
alterar a palavra-passe para uma da sua preferência;
 “Alterar palavra-passe”: utilize esta opção para alterar a sua palavra-passe;

Após efetuado o Login, surgirá o menu “Multibancos” onde poderá aceder às várias
funcionalidades do serviço.

IFMB 8
IFMB – Manual Técnico

Menu “Multibancos”

Caso não lhe apareça o menu “Multibancos” as causas prováveis são:

 Ainda não efetuou o “Login” (caso tenha efetuado o Login deverá aparecer-lhe no
canto superior direito da página 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 então 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 referência multibanco.

2 3

Exemplo do ecrã de consulta de pagamentos

O quadro de pagamentos é constituída 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 Técnico

 Referência MB: Referência multibanco paga;

 ID: ID (habitualmente o nº da encomenda ou do cliente). Está embutido na referência
também (4º a 7º caracteres);
 Valor Pago: Valor pago pelo cliente;
 Tarifa: Tarifa cobrada pela Ifthen;
 Valor Líquido: Valor pago deduzido da tarifa;

Na parte superior da página (área 2 ), pode definir os filtros pretendidos para a informação a
apresentar. Pode nomeadamente filtrar por entidade e sub-entidade (no caso de ter mais do
que uma), por ano e mês de processamento. Sempre que altere os filtros ou sempre que quiser
atualizar o quadro de pagamentos terá que clicar no botão “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 estão também condicionadas pelos filtros definidos na área 3 . Ou seja, se
pretender saber se uma determinada referência foi paga numa qualquer data do passado, terá
que configurar o filtro do ano e do mês para o período no qual deseja pesquisar (ou colocar
‘Todos’ para pesquisar em todos os anos/meses).

Pode também ordenar o quadro pelo campo que quiser, simplesmente clicando no título 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 informação do quadro agrupada por esse campo, sendo
inclusivamente apresentados sub-totais por esse campo.

Caso pretenda exportar a informação do quadro de pagamentos para Excel (XLS), PDF, RTF
ou CSV basta clicar no botão respetivo (na área ).
5

2.4. Back-Office: Consulta de Faturação

Selecionando o menu “Multibancos>Consulta de Faturação” tem acesso às faturas/recibo

emitidas mensalmente pela Ifthen relativas aos custos deste serviço.

IFMB 10
IFMB – Manual Técnico

O quadro onde aparecem as faturas tem um funcionamento em tudo semelhante ao quadro

dos pagamentos descrito anteriormente.

2.5. Back-Office: Gerar Referências

Selecionando o menu “Multibancos>Gerar Referências” tem acesso à área de geração de

referências. Como descrito no ponto 1 deste manual, esta é apenas uma das formas de gerar
referências.

Para gerar uma referência proceda do seguinte modo:

1. Escolha a sua entidade e sub-entidade;

2. Indique um ID e o valor a pagar. O ID é um número entre 0 e 9999 que fará parte
integrante da referência 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 botão “Gerar Referência”

Deverá disponibilizar sempre ao seu cliente a Entidade, Referência e Valor para ele poder
efetuar o pagamento.

IFMB 11
IFMB – Manual Técnico

2.6. Back-Office: Testar Referências

Selecionando o menu “Multibancos>Testar Referências” tem acesso à área de teste de

referências.
Não necessita de testar as referências que gerou pelo método anteriormente descrito. Esta
opção é mais utilizadas para:
 Caso um cliente o contacte a informar que não está a c onseguir pagar uma
determinada referência multibanco, pode utilizar esta opção para verificar se a mesma
está correta (o cliente pode ter se enganado ao tomar nota da referência ou estar a
trocar algum dígito);
 Se fizer a implementação da geração das referências num site ou noutro software,
pode utilizar esta opção para validar se as referências foram corretamente calculadas;

2.7. Back-Office: Alterar palavra-passe

Selecionando o menu “Multibancos>Alterar palavra-passe” tem acesso à área de alteração da

palavra-passe de acesso ao back office.

IFMB 12
IFMB – Manual Técnico

3. O algoritmo de geração das referências

No caso de necessitarem, por algum motivo, de desenvolver o cálculo das nossas referências
multibanco, deixamos aqui a explicação passo-a-passo do algoritmo de geração das referências.

No sistema multibanco existem 3 conjuntos de dígitos utilizados pelo cliente para efetuar o
pagamento: Entidade, Referência e Valor.

Exemplo:

Pagamento por Multibanco

ou Homebanking

Entidade: 11604

Referência: 999 123 490

Valor: 25,86 €

O talão emitido pela caixa automático 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, não deverá utilizar esta entidade e sub-entidade mas
sim a entidade e sub-entidade que vos foi atribuída pela Ifthen aquando da adesão ao serviço!

Esta caixa deve ser impressa no documento de venda (usualmente no canto inferior esquerdo) ou,
no caso do comércio eletrónico, apresentada/impressa pelo browser e, preferencialmente, enviada
também por e-mail nos detalhes da encomenda.

A data limite de pagamento pode ser também apresentada, mas é trans parente para o sistema
que aceitará pagamentos em qualquer data, mesmo posteriores.

Os terminais multibanco aceitam também o pagamento da mesma referência mais do que uma
vez, pelo que o tratamento de pagamentos duplicados deverá depois ser tratado
administrativamente.

Entidade

A entidade terá sempre 5 dígitos e será fornecida pela IFTHEN.

Valor

Valor a pagar com no máximo 8 dígitos (excluindo o separador decimal) : XXX XXX,XX

IFMB 13
IFMB – Manual Técnico

No caso de valores inteiros devem-se visualizar sempre as duas casa decimais (por
exemplo 25,00 e não apenas 25).

Pode-se incluir ou não o símbolo do Euro (€) á frente do valor.

Referência

A referência é composta sempre por 9 dígitos (em grupos de 3 facilita a visualização) e no

nosso sistema é composta do seguinte modo:

SSSDDDDCC

Em que

SSS: três dígitos que identificam a sub-entidade (o vendedor). Este código é atribuído
pela IFTHEN.

DDDD: ID - quatro dígitos 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 dígitos, pelo que caso o nº do
documento/encomenda ou o nº do cliente tenha mais que 4 dígitos terá que
utilizar apenas os 4 mais à direita, caso tenha menos de 4 dígitos deverá
preencher os restantes com zeros à esquerda.

CC: dois dígitos de controlo (check-digits). Serve para o terminal validar se a

informação está correta. Nota: Se o dígito de controlo só tiver um algarismo terá
que formatá-lo para 2 algarismos colocando 0 (zero) á esquerda.

No exemplo de cima:
11604 é o código da entidade;
999 é o código da sub-entidade;
1234 é o ID - nº do documento/encomenda a ser pago ou o número do v/ cliente;
90 são os dígitos de controlo;
25,86 € é o valor a pagar.

Cálculo dos dígitos de controlo

a) Concatenar numa string: os 5 dígitos da entidade + os 3 dígitos da sub-
entidade + 4 dígitos do ID + os 8 dígitos do valor (sem separador decimal e
colocando zeros á esquerda para dar 8 caracteres.

No nosso exemplo ficaria: 11604999123400002586

b) Fazer a seguinte operação:

Resultado1=
51 x 1º dígito +
73 x 2º dígito +
17 x 3º dígito +
89 x 4º dígito +
38 x 5º dígito +
62 x 6º dígito +

IFMB 14
IFMB – Manual Técnico

45 x 7º dígito +
53 x 8º dígito +
15 x 9º dígito +
50 x 10º dígito +
5x 11º dígito +
49 x 12º dígito +
34 x 13º dígito +
81 x 14º dígito +
76 x 15º dígito +
27 x 16º dígito +
90 x 17º dígito +
9x 18º dígito +
30 x 19º dígito +
3x 20º dígito

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 operação:

Resultado final = 98 – (resultado1 mod 97) sendo mod o resto da divisão

inteira

No nosso exemplo: resultado final = 98 – (2627 mod 97) = 98 – 8 = 90

Os dígitos de controlo seriam então 90

Nota: caso o dígito 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 Referências
Imediatamente após ser gerada a referência, ela pode ser paga nos terminais Multibanco (ou
HomeBanking, Telemultibanco ou MBSpot) na opção Pagamento de Compras/Serviços (do
mesmo modo que as faturas da eletricidade, água, gás e telecomunic ações). Repare que não tem
que fazer o envio das referências que gerar para qualquer web servisse da Ifthen ou da SIBS . Elas
apenas têm que ser corretamente calculadas para poderem ser imediatamente pagas. Por outro
lado, as referências multibanco apenas podem ser pagas pelo valor para o qual foram geradas (o
valor entra no cálculo dos check-digits).

Teste das Referências

Apesar da função de cálculo das referências multibanco ser relativamente simples, teste o seu
funcionamento para diferentes valores e IDs utilizando o nosso aplicativo de validação (disponível
em https://www.ifthensoftware.com/downloads/ifmb/ifmultibanco.zip) ou o nosso back-office.
Verifique também se está a utilizar a entidade e sub-entidade que lhe foi atribuída pela IFTHEN.

Exemplos de Implementação

Pode fazer o download de exemplos de implementação deste algoritmo em várias linguagens

de programação, bem como módulos para as principais plataformas de e-commerce neste link:

https://www.ifthensoftware.com/downloads/ifmb/Exemplos_Implementacao.zip

IFMB 15
IFMB – Manual Técnico

4. Notificações dos Pagamentos

Existem diversas formas de aceder às notificações dos pagamentos efetuados através do

nosso serviço de pagamentos IFMB:

 Através do back-office na nossa página na internet em www.ifthensoftware.com, após

ter efetuado o registo com a chave de acesso que lhe disponibilizamos, onde os
pagamentos são atualizados em real-time;
 Através do e-mail instantâneo (em real-time) enviado sempre que há um pagamento,
para os e-mails que definiu para esse fim (caso tenha esta opção ativa);
 Através do e-mail resumo diário enviado diariamente com os pagamentos do dia
anterior;
 Através dos extratos mensais com todos os pagamentos do mês;
 Através da chamada ao nosso WebService;
 Através da chamada de um URL definido por vós – CallBack;

Os dois últimos pontos são os indicados para quem pretenda fazer o tratamento automático
dos pagamentos.

NOTA: A geração das referências multibanco não são efetuadas pelo nosso webservice, mas
apenas a notificação dos pagamentos

4.1. WebService

O webservice está disponível no seguinte endereço:

https://www.ifthensoftware.com/IfmbWS/WsIfmb.asmx

Os métodos GetPayments, GetPaymentsJson e GetPaymentsXml devolvem os pagamentos

efectuados na entidade e sub-entidade indicada.

A única diferença entre os três métodos é o formato em que a informação é 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 parâmetros a passar na chamada do método são:

 Chavebackoffice: Chave fornecida pela IFTHEN na assinatura do contrato.

Obrigatório.
 Entidade: Entidade (5 dígitos) fornecida pela IFTHEN na assinatura do contrato.
Obrigatório.
 Subentidade: Sub-Entidade (3 dígitos) fornecida pela IFTHEN na assinatura do
contrato. Obrigatório.

IFMB 16
IFMB – Manual Técnico

 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: Referência multibanco (9 dígitos) sobre a qual se pretende saber a
informação do pagamento. Facultativo.
 Valor: Valor em euros dos pagamentos que se pretende obter informação. Facultativo.
 Sandbox: Devem indicar 1 ou 0 no caso de utilizarem ou não a plataforma de testes.
Obrigatório.

O método pode ser chamado de várias formas, conforme as necessidades:

a) Se pretende obter todos os pagamentos ainda não pedidos, independentemente da

data/hora em que ocorreram, deverá passar apenas os parâmetros chavebackoffice,
entidade, subentidade. Todos os outros deverão ser deixados em branco.

Exemplo:
https://www.ifthensoftware.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 não 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 não 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 parâmetros chavebackoffice, entidade, subentidade, dtHrInicio,
dtHrFim. Todos os outros deverão ser deixados em branco.

Exemplo:
https://www.ifthensoftware.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 não as indicadas neste
exemplo.

Neste caso, serão sempre devolvidos os pagamentos, quer tenham sido ou não
anteriormente lidos.

IFMB 17
IFMB – Manual Técnico

c) Se pretende apenas saber se uma determinada entidade/referência/valor foi paga

deverá passar os parâmetros chavebackoffice, entidade, subentidade, referencia,
valor e opcionalmente a dtHrInicio e dtHrFim.

Exemplo:
https://www.ifthensoftware.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, referência e

valor indicados. Ter em atenção que podem existir mais do que um pagamento dessa
referência. Podem também ser passados os parâmetros da data/hora inicial e final.

d) Se pretende saber se uma determinada entidade/referência/valor foi paga fora do

ambiente de testes (sandbox) deverá passar os parâmetros chavebackoffice,
entidade, subentidade, referencia, valor, opcionalmente a dtHrInicio e dtHrFim e a
sandbox com o valor 0.

Exemplo:
https://www.ifthensoftware.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, referência e

valor indicados fora do ambiente de testes. Ter em atenção que podem existir mais do
que um pagamento dessa referência. Podem também ser passados os parâmetros da
data/hora inicial e final.

e) Se pretende saber se uma determinada entidade/referência/valor foi paga a partir do

ambiente de testes (sandbox) deverá passar os parâmetros chavebackoffice,
entidade, subentidade, referencia, valor, opcionalmente a dtHrInicio e dtHrFim e a
sandbox com o valor 1.

Exemplo:
https://www.ifthensoftware.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, referência e

valor indicados no ambiente de testes. Ter em atenção que podem existir mais do que
um pagamento dessa referência. Podem também ser passados os parâmetros da
data/hora inicial e final.

IFMB 18
IFMB – Manual Técnico

Estes métodos devolvem a seguinte informação para cada pagamento (1 ou mais):

 Entidade – entidade utilizada no pagamento (5 dígitos)

 Referencia – referência multibanco paga (9 dígitos)
 Valor – valor pago em euros
 Id – id utilizado na geração da referência multibanco (4 dígitos)
 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 serviço
 ValorLiquido – valor pago deduzido da tarifa
 CodigoErro – código de erro
 MensagemErro – mensagem de erro

Código Mensagem
0 Sucesso.
1 Não existem pagamentos.
2 Erro nas Datas/Horas.
3 Chave inválida.
9 Erro desconhecido.

4.2. Chamada de URL – “Call Back”

Como alternativa ao WebService, podem utilizar o método de “Call Back” para automatizar o
processamento dos pagamentos.

Neste caso, em vez de chamarem o nosso WebService periodicamente para verificar se

existem pagamentos, nós chamaremos um URL definido por vós sempre que ocorram
pagamentos.

Este URL deverá ser previamente definido por vós e enviado à Ifthen por e-mail.

Deverão também definir e enviar à Ifthen uma chave “Anti-Phishing“ (uma string com o máximo
de 50 caracteres) que será devolvida como parâmetro quando chamarmos o URL, para que
possam verificar a autenticidade da mesma.

O URL indicado por vós deverá incluir os parâmetros que pretendem que sejam devolvidos
(entre parêntesis retos []):

 [CHAVE_ANTI_PHISHING] – String definida previamente por vós para autenticarem a

resposta. Obrigatório.;
 [ENTIDADE] – Entidade multibanco. Obrigatório.;
 [REFERENCIA] – Referência multibanco. Obrigatório.;
 [VALOR] – Montante pago. Obrigatório.;
 [DATA_HORA_PAGAMENTO] – Data/Hora de pagamento (devolve no formato dd-
MM-yyyy HH:mm:ss). Facultativo.;

IFMB 19
IFMB – Manual Técnico

 [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 não tem de devolver qualquer valor. O sucesso do nosso pedido é determinado
pelo código HTTP obtido: Caso devolva o código HTTP 200 a Ifthen considera que a chamada
foi efetuada com sucesso, caso devolva um código diferente (HTTP 400, 500 ou outro) então a
Ifthen considera que a chamada não teve sucesso e tentará novamente mais tarde (tentará 13
vezes sendo que as primeiras 8 serão de 5 em 5 minutos e as restantes de hora em hora).
Caso nessas 13 tentativas não obtenha a resposta OK, não voltará a tentar, e enviará um e-
mail a notificar o erro permanente.

IFMB 20