ifthenpay | pagamentos digitais para a sua empresa

NOTA: Para novas integrações utilizar a nova versão da API.

API MBWAY v2 - REST

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 desenvolver a integração de raiz, de seguida a descrição do webservice para efetuar a solicitação de pagamento MBWAY e o callback de resposta quando o pagamento é efetuado.

A) Webservice para solicitação de pagamento MBWAY

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

https://mbway.ifthenpay.com/ifthenpaymbw.asmx

Os métodos SetPedido e SetPedidoJson permitem o envio de pedidos de pagamentos MBWay.

A única diferença entre os 2 métodos é o formato em que o resultado é devolvido. No primeiro (SetPedido) é devolvido no formato SOAP (1.1 e 1.2); no segundo (SetPedidoJson) é devolvido em formato JSON.

Para além dos métodos acima referidos, existem ainda os métodos EstadoPedidos e EstadoPedidosJson. Ambos devolvem o estado em que se encontra o pedido. A diferença entre os dois é o formato do resultado conforme já descrito acima.  

Todos os métodos referidos podem ser invocados por GET ou POST.

Método SetPedido ou SetPedidoJSON.

Parâmetros:

• MbWayKey - (Obrigatório) fornecido pela IFTHENPAY aquando da celebração do contrato.
• canal - (Obrigatório) no caso desta API terá de ter sempre o valor constante “03”.
• referencia – (Obrigatório) Identificador do pagamento a definir pelo cliente (ex. número da fatura, encomenda, etc…); Máximo 15 caracteres.
• valor - (Obrigatório) valor a cobrar.
• nrtlm - (Obrigatório) Número do telemóvel do cliente.
• email - (Opcional) email do cliente.
• descricao - (Obrigatório) descrição do pagamento (pode utilizar a tag [REFERENCIA] caso pretenda que a descrição seja igual à referência); Máximo 50 caracteres.

Resultado da resposta:

<RespostaPedido xmlns="https://www.ifthenpay.com/">

  <IdPedido>string</IdPedido>

  <Valor>string</Valor>

  <CodigoMoeda>string</CodigoMoeda>

  <Estado>string</Estado>

  <DataHora>string</DataHora>

   <MsgDescricao>string</MsgDescricao>

</RespostaPedido>

• IdPedido – id gerado automaticamente, poderá ser guardado para consulta posterior do estado do pedido;
• Valor - Valor do pedido em euros;
• CodigoMoeda – Terá sempre o valor 9782;
• Estado – Indica o sucesso ou erro da operação: (“000” = Pedido enviado com sucesso para o cliente. Caso o valor seja diferente de “000” é necessário analisar o campo MsgDescricao, ex: “113” = número de telemóvel inválido);
• DataHoraPedido – Data e Hora em que o pedido foi efetuado na SIBS;
• MsgDescricao – Mensagem associada ao estado da operação.

Após o pedido ser efetuado e assim que o cliente aceitar o pagamento na App MBWAY será notificado pela IFTHENPAY do mesmo modo que as referências multibanco, ou seja, por “push notification”, se tiver a nossa app instalada com essa opção ativa, por email ou consultar diretamente no backoffice.

Caso pretenda ser notificado por callback deverá pedir previamente à ifthenpay a ativação do callback.

Nota: para efetuarem testes de pedidos aconselhamos a criarem uma conta na App MBWAY e enviar os pedidos para esse número e assim que receberem a notificação não aceitem o pagamento, caso contrário o pagamento será processado normalmente.

Método EstadoPedidos ou EstadoPedidosJSON.

Caso pretenda consultar o estado do(s) pedido(s) poderá invocar qualquer um destes métodos.

Parâmetros:

• MbWayKey - Fornecido pela IFTHENPAY aquando da celebração do contrato;
• canal - No caso desta API terá de ter sempre o valor constante “03”;
• idspagamento – id devolvido (IdPedido) aquando da operação SetPedido/SetPedidoJson;

Tabela com os possíveis Estados (código, descrição):

B) Callback MBWAY

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] – Token definido previamente por vós para autenticarem a resposta;
• [REFERENCIA] – Referência MBWAY;
• [ID_TRANSACAO] – Id da Transação (IdPedido);
• [VALOR] – Montante pago;
• [DATA_HORA_PAGAMENTO] – Data/Hora de pagamento (devolve no formato dd-MM-yyyy HH:mm:ss);
• [ESTADO] – Estado do Pedido. (retorna “PAGO” sempre que o pagamento seja aceite, em devoluções retorna "DEVOLVIDO");

Exemplo de URL:
http://www.yoursite.com/callback.php?chave=[CHAVE_ANTI_PHISHING]&referencia=[REFERENCIA]&idpedido=[ID_TRANSACAO]&valor=[VALOR]&datahorapag=[DATA_HORA_PAGAMENTO]&estado=[ESTADO]

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