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

[email protected]

[email protected]

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:


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:



&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:




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:




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.

manual ifmb

Documents