INFORMATION


WE WOULD LIKE TO INFORM YOU THAT THE NEW API DOCUMENTATION IS NOW AVAILABLE. THIS UPDATE OFFERS AN EVEN MORE SIMPLIFIED AND EFFICIENT WAY TO INTEGRATE OUR SERVICES.

CHECK THE NEW DOCUMENTATION


Welcome to the new Rest MBWAY API. This API allows you to make MBWAY payment requests.


Before implementing it, check whether there is already integration with the platform you are using developed by Ifthenpay, the platform manufacturer or a third party.


A) MBWAY Payment request endpoint


The MBWay webservice is available at the following address: 


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


Method: POST


Request


JSON Format

{
    "mbWayKey": "MBWAY_KEY", //(string) mandatory (assigned by ifthenpay)
    "orderId": "ORDER_ID", //(string) mandatory (15 chars max)
    "amount": "AMOUNT", //(string) mandatory (decimal separator ".")
    "mobileNumber": "MOBILE_NUMBER", //(string) mandatory
    "email": "EMAIL", //(string) optional (100 chars max)
    "description": "DESCRIPTION", //(string) optional (100 chars max)
}

Note: For Portuguese mobile numbers, you don't need to send a country code, otherwise you'll need to add the country code. (Example of a foreign number: 34#912345678)


Final example of the request. 

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


Response:


JSON format


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


You should always store the RequestId from the response.


Below the response codes you can get when initializing the payment request:


000 - Request initialized successfully (pending acceptance).

100 - The initialization request could not be completed. You can try again.

122 - Transaction declined to the user.

999 - Error on initializing the request. You can try again.



B) Endpoint for checking payment status


Method: GET


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


mbWayKey - assigned by ifthenpay.

requestId - Obtained in response to the request.


Response:


JSON Format

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


Successful payments always return Status="000" and Message="Success".


Below the response codes you can get when checking payment status:


000 - Transaction successfully completed (Payment confirmed).

020 - Transaction rejected by the user.

101 - Transaction expired (the user has 4 minutes to accept the payment in the MB WAY App before expiring)

122 - Transaction declined to the user. 



C) Callback MBWAY (Webhook)


Once the order has been placed and payment has been confirmed, you will be notified by ifthenpay via the usual channels, i.e. by push notification, if you have our app installed and have this option activated, by email, or you can check directly in our backoffice. 


If you wish to be notified by callback, you must first ask ifthenpay to activate the callback (webhook).


Example of a Callback URL:


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


Example of Callback URL called (after confirmed payment):


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


Support:


ifthenpay guarantees free technical assistance to all customers and the following channels can be used:


- by e-mail: [email protected]

- by phone:  808 222 777 | +351 227 660 871 

- Open a ticket here