Bem-vindo à nova API Rest MBWAY. Esta API permite efetuar pedidos de pagamentos MBWAY.


Antes de implementar, 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: 


Se necessitar de implementar a integração de raiz, deve seguir este manual da API para efetuar a solicitação de pagamentos MBWAY e implementar o callback (webhook) para receber a comunicação dos pagamentos em tempo real.



A) Endpoint para solicitação de pagamento MBWAY


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


https://ifthenpay.com/api/spg/payment/mbway


Método: POST


Pedido


Formato JSON

{
    "mbWayKey": "MBWAY_KEY", //(texto) obrigatório (atribuído pela ifthenpay)
    "orderId": "ORDER_ID", //(texto) obrigatório (máximo 15 caracteres)
    "amount": "MONTANTE", //(texto) obrigatório (separador decimal ".")
    "mobileNumber": "MOBILE_NUMBER", //(texto) obrigatório
    "email": "EMAIL", //(texto) opcional (máximo 100 caracteres)
    "description": "DESCRICAO", //(texto) opcional (máximo 100 caracteres)
}

Nota: Para números de telemóvel nacional não é necessário enviar indicativo, caso contrário terá de adicionar o indicativo do respetivo país. (Exemplo de um número estrangeiro: 34#912345678)


Exemplo final do pedido. 

{
    "mbWayKey": "ABC-123456",
    "orderId": "12345",
    "amount": "100.50",
    "mobileNumber": "351#912345678",
    "email": "",
    "description": "order 123456"
}


Resposta:


Formato JSON 


{
    "Amount": "33.61",
    "Message": "Pending",
    "OrderId": "1887",
    "RequestId": "i2szvoUfPYBMWdSxqO3n",
    "Status": "000"
}


Devem sempre associar o RequestId devolvido na resposta ao vosso pedido para posterior utilização .


Na resposta do pedido devem ter em consideração os seguintes códigos:


000 - Pedido inicializado com sucesso (encontra-se pendente de aceitação);

100 - Não foi possível concluir o pedido de inicialização. Pode efetuar nova tentativa;

122 - Operação recusada ao utilizador;

999 - Erro ao inicializar o pedido. Pode efetuar nova tentativa;



B) Endpoint para consulta do estado do pagamento


Método: GET


https://ifthenpay.com/api/spg/payment/mbway/status?mbWayKey={mbWayKey}&requestId={requestId}


mbWayKey - atribuída pela ifthenpay

requestId - obtido na resposta do pedido.


Resposta:


Formato JSON

{
    "CreatedAt": "03-01-2024 15:15:06",
    "Message": "Success",
    "RequestId": "eR6mcnJzjFx7kOL1Ybdp",
    "Status": "000",
    "UpdateAt": "03-01-2024 15:15:16"
}


Pagamentos bem-sucedidos retornam sempre Status="000" e Message="Success".


Na consulta de estado devem ter em consideração os seguintes códigos:


000 - Operação concluída com sucesso;

020 - Operação recusada pelo utilizador;

101 - Operação expirada (o utilizador tem 4 minutos para aceitar o pagamento na App MB WAY)

122 - Operação recusada ao utilizador;



C) Callback MBWAY (Webhook)


Após o pedido ser efetuado e o pagamento for confirmado será notificado pela ifthenpay pelos canais habituais, ou seja, por “push notification”, se tiver a nossa app instalada e com essa opção ativa, por email ou pode consultar diretamente no nosso backoffice. 


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


Exemplo de URL de Callback:  


http://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&payment_datetime=[PAYMENT_DATETIME]


Exemplo de URL de Callback invocado (após pagamento confirmado):  


http://www.yoursite.com/callback.php?key=your_anti_phishing_key&orderId=1887&amount=33.61&requestId=i2szvoUfPYBMWdSxqO3n&payment_datetime=03-01-2024 15:15:16


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