ifthenpay | pagamentos digitais para a sua empresa

A ifthenpay integra com inúmeras plataformas de e-commerce, softwares de faturação e outros.

Antes de desenvolver, verifique se já existe integração com a plataforma que utiliza, desenvolvida pela ifthenpay, pelo fabricante da plataforma ou por terceiros.

Ver tópicos relacionados: 

• Plugins para plataformas de Ecommerce
• Integração com softwares de faturação
• API - Gerar URL PayByLink

Se necessitar de fazer a integração de raiz, segue a descrição do algoritmo de geração das referências em offline e a descrição do método de callback e web service para se quiser automatizar o tratamento dos pagamentos. Para a integração por este processo necessitará de um código de entidade (5 dígitos numéricos) e um código de subentidade (3 dígitos numéricos) atribuídos pela ifthenpay ao comerciante. Se não tiver essa entidade e subentidade contacte a ifthenpay. Neste formato de referências Multibanco não é possivel ter validades.

Existe uma forma alternativa de integração, geração de referências a pedido (online) , em que nos é efetuado um pedido de nova referência via API. Neste caso necessitará de uma MB KEY que a ifthenpay poderá fornecer ao comerciante. Pode encontrar a descrição dessa API aqui: API - Referências Multibanco a Pedido

A) 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.

* * * NOTA IMPORTANTE * * *

Em todos os exemplos neste manual iremos utilizar para fins demonstrativos a Entidade 11604 e a Subentidade 999. Em casos reais, não deverá utilizar esta entidade e subentidade mas sim a entidade e subentidade que vos foi atribuída pela IFTHENPAY 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 por defeito é transparente para o sistema que aceitará pagamentos em qualquer data, mesmo posteriores.

Os terminais multibanco aceitam também, por defeito, 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 IFTHENPAY.

Valor

Valor a pagar com no máximo 8 dígitos (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 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 subentidade (o vendedor). Este código é atribuído pela IFTHENPAY.

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ígito 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 subentidade;

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 subentidade + 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 +

45 x     7º dígito +

53 x     8º dígito +

15 x     9º dígito +

50 x     10º dígito +

5 x         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 +

9 x         18º dígito +

30 x     19º dígito +

3 x         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 das Referências

Imediatamente após ser gerada a referência (que é gerada em off-line), ela pode imediatamente 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 telecomunicações). Repare que não tem que fazer o envio das referências que gerar para qualquer web service da IFTHENPAY 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.ifthenpay.com) ou o nosso BackOffice. Verifique também se está a utilizar a entidade e subentidade que lhe foi atribuída pela IFTHENPAY.

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

B) APIWebservice para ler pagamentos efetuados

Uma das formas de automatizar o processamento dos pagamentos efetuados é através da leitura dos mesmos por webservice. Sempre que possível, nomeadamente nas plataformas online, devem utilizar em vez do webservice, o método callback (descrito no capítulo seguinte).

O webservice para ler os pagamentos efetuados está disponível no seguinte endereço:

https://ifthenpay.com/ifmbws/ifmbws.asmx

Os métodos getPayments, getPaymentsJson e getPaymentsXml devolvem os pagamentos efetuados na entidade e subentidade 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 IFTHENPAY na assinatura do contrato. Obrigatório.
• Entidade: Entidade (5 dígitos) fornecida pela IFTHENPAY na assinatura do contrato. Facultativo.
• Subentidade: Subentidade (3 dígitos) fornecida pela IFTHENPAY na assinatura do contrato. Facultativo.
• 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:

• Se pretende obter todos os pagamentos efetuados entre duas datas/horas deverá passar os parâmetros chavebackoffice, entidade, subentidade, dtHrInicio, dtHrFim e sandbox. Todos os outros deverão ser deixados em branco. 

Exemplo:
https://ifthenpay.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=&sandbox=0 

Devolve os pagamentos da entidade 11604, subentidade 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 subentidade e não as indicadas neste exemplo.

• Se pretende apenas saber se uma determinada entidade/referência/valor foi paga deverá passar os parâmetros chavebackoffice, entidade, subentidade, referencia, valor e sandbox e opcionalmente a dtHrInicio e dtHrFim. 

Exemplo:
https://ifthenpay.com/ifmbws/ifmbws.asmx/getPayments?chavebackoffice=0000-0000-0000-0000&entidade=11604&subentidade=999&dtHrInicio=&dtHrFim=&referencia=999123420&valor=10.25&sandbox=0

Devolve, caso existam, os pagamentos efetuados 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. 

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

• Entidade – entidade utilizada no pagamento (string)
• Sub_Entidade - subentidade utilizada no pagamento (string)
• 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) Callback para receber os pagamentos efetuados por referência multibanco

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.

O URL e Chave Anti-Phising deverá ser previamente definido por vós e configurado no backoffice Ifthenpay ou enviado por email para callback@ifthenpay.com. 

Deverão também definir e enviar à IFTHENPAY 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.;
• [ENTIDADE] – Entidade multibanco.;
• [REFERENCIA] – Referência multibanco.;
• [VALOR] – Montante pago;
• [DATA_HORA_PAGAMENTO] – Data/Hora de pagamento (devolve no formato dd-MM-yyyy HH:mm:ss);
• [TERMINAL] – Terminal utilizado no pagamento;

Exemplos de URL:
 
http://www.yoursite.com/callback.php?chave=[CHAVE_ANTI_PHISHING]&entidade=[ENTIDADE]&referencia=[REFERENCIA]&valor=[VALOR]&datahorapag=[DATA_HORA_PAGAMENTO]&terminal=[TERMINAL]
 
http://www.yoursite.com/callback.aspx?chave=[CHAVE_ANTI_PHISHING]&entidade=[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 IFTHENPAY considera que a chamada foi efetuada com sucesso, caso devolva um código diferente (HTTP 400, 500 ou outro) então a IFTHENPAY 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.

Suporte:

A IFTHENPAY garante assistência técnica gratuita a todos os clientes e podem ser utilizados os seguintes canais:

- Através do e-mail suporte@ifthenpay.com

- Através do telefone:  808 222 777  |  +351 227 660 871 

- Através da abertura de um ticket aqui