The Malipo Payments API is a payment system aggregation platform designed to allow merchants to accept payments from customers using a variety of payment providers through a single access point. The API Gateway offered by Malipo consolidates all payment services, enabling merchants to integrate seamlessly with different payment methods without the need for bilateral integrations or specialized infrastructure like VPN connections.
\nKey features of the Malipo Payments API include:
\nUnified Payment Integration: Merchants can access multiple payment services (e.g., mobile money, bank payments, credit/debit cards) through one API endpoint, simplifying integration and reducing development effort.
\nAPI Gateway: It exposes all payment services to merchants via web applications, providing a straightforward way to handle different payment channels.
\nFlexible Payment Initiation: Customers or merchants can initiate payments using various channels, including USSD and mobile applications.
\nThis API streamlines the payment process for businesses, making it easier to manage and support diverse payment methods in a centralized manner.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"19520622","collectionId":"61f12e32-7ca7-412f-8492-319119721e43","publishedId":"2sAXqqc3GD","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-09-17T13:22:45.000Z"},"item":[{"name":"Payments","item":[{"name":"Request Payment","event":[{"listen":"test","script":{"id":"f01dac75-6fb0-4a3e-a36b-6e7b5917635f","exec":["// Stores the transactionId in an environment or global variable","var transactionId = pm.response.json().data.transaction_id;","pm.environment.set(\"transactionId\", transactionId);","// Stores the account number in an environment or global variable","var accountNumber = pm.response.json().data.account_number;","pm.globals.set(\"accountNumber\", accountNumber);"],"type":"text/javascript","packages":{}}}],"id":"e13d17cf-2735-48af-9a22-76d2bb9a268e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"Your_App_ID_Here","description":"This is your unique API Key of your project accessible in the MobiPay dashboard.
\n","type":"text"},{"key":"x-app-id","value":"Your_API_Key_Here","description":"This is your Project ID also refered to App ID accessible in the MobiPay dashboard.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"merchantTrxId\": \"UAT-111903104\",\r\n \"customerPhone\": \"265994791131\",\r\n \"bankId\": 1,\r\n \"amount\": 50\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://app.malipo.mw/api/v1/paymentrequest","description":"This endpoint allows you to make a POST request to initiate a payment request.
\nmerchantTrxId (string, required): The unique identifier for the merchant transaction.customerPhone (string, required): The phone number of the customer.bankId (integer, required): The ID of the bank.amount (integer, required): The amount of the payment.Status: 201
\nContent-Type: application/json
\nmessage (string): A message related to the payment request.
data (object):
transaction_id (string): The Unique Id of the transaction in MobiPay system.
merchant_trx_id (string): The unique merchant transaction ID.
account_number (string): The account number/projectId under which the payment is made.
wallet (string): The wallet used for the transaction. Same as customerPhone number.
amount (integer): The amount of the transaction.
narration (string): Additional information or description of the transaction.
transaction_type_id (integer): The ID of the transaction type.
payment_channel_id (integer): The ID of the payment channel used.
This HTTP POST request is used to initiate a refund for a specific transaction by providing the transaction ID in the URL. Upon successful execution, the API returns a 200 status with a JSON response containing the status of the refund, the reversal transaction ID, and the customer reference.
\nThe response body includes the following fields:
\nstatus: Indicates the status of the refund process.
\nreversal_trans_id: Represents the Unique MobiPay ID of the reversal transaction.
\ncustomer_ref: Denotes the reference included in the notification sent to the customer.
\nThis endpoint allows users to efficiently process refunds for transactions and retrieve essential information related to the refund operation.
\n","urlObject":{"path":["payment","refund",":transaction_id"],"host":["https://app.malipo.mw/api/v1"],"query":[],"variable":[{"description":{"content":"MobiPay Transaction ID
\n","type":"text/plain"},"type":"any","value":"IP240330134348","key":"transaction_id"}]}},"response":[{"id":"afb132a4-46f0-4d61-af86-c305dad185d3","name":"Refund","originalRequest":{"method":"POST","header":[{"key":"x-app-id","value":"Your_App_ID_Here","type":"text"},{"key":"x-api-key","value":"Your_API_Key_Here","type":"text"}],"url":{"raw":"https://app.malipo.mw/api/v1/payment/refund/:transaction_id","protocol":"https","host":["app","malipo","mw"],"path":["api","v1","payment","refund",":transaction_id"],"variable":[{"key":"transaction_id","value":"IP240330134348","description":"MobiPay Transaction ID"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Tue, 09 Apr 2024 11:28:04 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"reversal_trans_id\": \"RF240409277738\",\n \"customer_ref\": \"MP240330.1022.H12828\"\n}"}],"_postman_id":"ed01bcde-bc3a-452e-90df-00ef1d7cc4ad"},{"name":"Disbursement","event":[{"listen":"test","script":{"id":"b94d7904-49ab-477c-8902-816da1db221c","exec":["pm.test(\"Response status code is 200\", function () {"," pm.response.to.have.status(200);","});","","pm.test(\"Response is a JSON object with message and data properties\", function () {"," var jsonData = pm.response.json();"," pm.expect(jsonData).to.be.an('object').that.has.all.keys('message', 'data');","});","","pm.test(\"Data property contains transaction_id with specific properties\", function () {"," var transactionId = pm.response.json().data.transaction_id;"," pm.expect(transactionId).to.be.an('object').that.has.all.keys('merchantTrxId', 'transaction_id', 'account_number', 'customerPhone', 'bankId', 'amount', 'transaction_type_id');","});"],"type":"text/javascript","packages":{}}}],"id":"6d076c47-d85f-492e-91e9-935966f32218","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-app-id","value":"Your_App_ID_Here","type":"text"},{"key":"x-api-key","value":"Your_API_Key_Here","type":"text"}],"body":{"mode":"raw","raw":"\r\n{\r\n \"merchantTrxId\": \"111903106\",\r\n \"wallet\": \"265994791131\",\r\n \"bankId\": 1,\r\n \"amount\": 50\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://app.malipo.mw/api/v1/payments/withdrawal","description":"This endpoint allows you to execute a withdrawal payment.
\nmerchantTrxId (string, required): The merchant transaction ID.
wallet (string, required): The user's wallet phone number.
bankId (integer, required): The ID of the bank.
amount (integer, required): The withdrawal amount.
Upon successful execution, the API returns a JSON response with the following structure:
\n{\n \"message\": \"string\",\n \"data\": {\n \"transaction_id\": {\n \"merchantTrxId\": \"string\",\n \"transaction_id\": \"string\",\n \"account_number\": \"string\",\n \"customerPhone\": \"string\",\n \"bankId\": 0,\n \"amount\": 0,\n \"transaction_type_id\": 0\n }\n }\n}\n\nmessage (string): A message indicating the status of the withdrawal request.data (object): The data object containing the transaction details.transaction_id (object): The transaction details.merchantTrxId (string): The merchant transaction ID.transaction_id (string): The unique transaction ID.account_number (string): The account number for the withdrawal.customerPhone (string): The customer's phone number.bankId (integer): The ID of the bank.amount (integer): The withdrawal amount.transaction_type_id (integer): The ID representing the transaction type.The URL endpoint is provided by merchant and is where MobiPay will post a transaction status updated of what transpired when the customer was delivered a payment request.
\nstatus Can either be Completed or Failed.
merchant_txn_id Transaction reference originated.
transaction_id MobiPay transaction reference.
customer_reference Third-Party system transacton ID delivered to he customer for their reference.
This request does not expect any response and will not be affected by anything the merchant responds with.
\n","urlObject":{"protocol":"https","path":["api","payments","callback"],"host":["x01","backend","matikiti","mw"],"query":[],"variable":[]}},"response":[],"_postman_id":"d60c471d-da96-49e8-9199-d692b05a6fcc"}],"id":"0309f851-49ad-4e6f-bddc-901cc6b1002f","_postman_id":"0309f851-49ad-4e6f-bddc-901cc6b1002f","description":""},{"name":"Information Retrieval","item":[{"name":"Bank List","event":[{"listen":"test","script":{"id":"a3d49cba-e438-4483-8f1c-844dd6bb7d69","exec":["pm.test(\"Response status code is 200\", function () {\r"," pm.response.to.have.status(200);\r","});\r","\r","\r","pm.test(\"Response has the required fields - id, name, type, and logo_url\", function () {\r"," const responseData = pm.response.json();\r"," \r"," pm.expect(responseData).to.be.an('array');\r"," responseData.forEach(function(bank) {\r"," pm.expect(bank).to.include.all.keys('id', 'name', 'type', 'logo_url');\r"," });\r","});\r","\r","\r","pm.test(\"Name is a non-empty string\", function () {\r"," const responseData = pm.response.json();\r"," \r"," pm.expect(responseData).to.be.an('array');\r"," responseData.forEach(function(bank) {\r"," pm.expect(bank.name).to.be.a('string').and.to.have.lengthOf.at.least(1, \"Name should not be empty\");\r"," });\r","});\r","\r","\r","pm.test(\"Type is a non-empty string\", function () {\r"," const responseData = pm.response.json();\r"," \r"," pm.expect(responseData).to.be.an('array');\r"," responseData.forEach(function(bank) {\r"," pm.expect(bank.type).to.be.a('string').and.to.have.lengthOf.at.least(1, \"Type should not be empty\");\r"," });\r","});\r","\r","\r","pm.test(\"Verify that the logo_url is either null or a valid URL\", function () {\r"," const responseData = pm.response.json();\r","\r"," pm.expect(responseData).to.be.an('array');\r"," responseData.forEach(function(bank) {\r"," pm.expect(bank.logo_url).to.satisfy(function (url) {\r"," return url === null || (typeof url === 'string' && url.match(/(http|https):\\/\\/(\\S+)/) !== null);\r"," }, \"logo_url should be either null or a valid URL\");\r"," });\r","});\r","pm.test(\"Each bank in the response has a non-empty id, name, and type\", function () {\r"," pm.response.json().forEach(function(bank) {\r"," pm.expect(bank.id).to.be.a('number').and.to.be.greaterThan(0, \"ID should be a non-empty number\");\r"," pm.expect(bank.name).to.be.a('string').and.to.have.lengthOf.at.least(1, \"Name should not be empty\");\r"," pm.expect(bank.type).to.be.a('string').and.to.have.lengthOf.at.least(1, \"Type should not be empty\");\r"," });\r","});\r","\r","pm.test(\"Verify that the logo_url is either null or a valid URL for each bank\", function () {\r"," pm.response.json().forEach(function(bank) {\r"," pm.expect(bank.logo_url).to.satisfy(function (url) {\r"," return url === null || (typeof url === 'string' && url.match(/(http|https):\\/\\/(\\S+)/) !== null);\r"," }, \"logo_url should be either null or a valid URL\");\r"," });\r","});"],"type":"text/javascript","packages":{}}}],"id":"f3192102-3e63-4716-b22c-bfb7b7768ef2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-app-id","value":"Your_App_ID_Here","type":"text"},{"key":"x-api-key","value":"Your_API_Key_Here","type":"text"}],"url":"https://app.malipo.mw/api/v1/banklist","description":"This endpoint makes an HTTP GET request to retrieve a list of banks from the specified URL. The response will be in JSON format and will include an array of objects, each representing a bank with its id, name, type, and logo URL.
\nExample Response:
\n[\n {\n \"id\": 0,\n \"name\": \"\",\n \"type\": \"\",\n \"logo_url\": null\n }\n]\nThis endpoint allows you to retrieve payment details for a specific transaction by providing the transaction ID in the URL.
\nThe response will be in JSON format with a 200 status code. The response includes various details such as application name, app ID, transaction ID, merchant transaction ID, customer reference, payment provider, currency, customer wallet, narration, amount, fee, status, and timestamp.
\nAdd documentation.
\n","urlObject":{"path":["payment","enquire",":merchantTrxId"],"host":["https://app.malipo.mw/api/v1"],"query":[],"variable":[{"type":"any","value":"UAT-111903104","key":"merchantTrxId"}]}},"response":[{"id":"cfa90cab-84f5-4c64-a44c-4176f4bd4d19","name":"Transaction Enquiry Example","originalRequest":{"method":"GET","header":[{"key":"x-app-id","value":"Your_App_ID_Here","type":"text"},{"key":"x-api-key","value":"Your_API_Key_Here","type":"text"}],"url":{"raw":"https://app.malipo.mw/api/v1/payment/enquire/:transaction_id","protocol":"https","host":["app","malipo","mw"],"path":["api","v1","payment","enquire",":transaction_id"],"variable":[{"key":"transaction_id","value":"CP240326358073","description":"MobiPay Transaction ID"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 28 Mar 2024 07:51:28 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Transaction record found!\",\n \"data\": {\n \"application_name\": \"MobiPay UAT\",\n \"app_id\": \"456475567\",\n \"transId\": \"CP240326358073\",\n \"merchant_trx_id\": \"72522059\",\n \"customer_ref\": \"BCQ60B7GLQ\",\n \"payment_provider\": \"TNM Mpamba\",\n \"currency\": \"MWK\",\n \"customer_wallet\": \"265882997445\",\n \"narration\": \"Customer Payout\",\n \"amount\": \"-60.50\",\n \"fee\": \"-2.06\",\n \"status\": \"Completed\",\n \"timestamp\": \"2024-03-26 12:25:02\"\n }\n}"}],"_postman_id":"4f26c856-7d01-4589-b52f-bc914e6e0a59"},{"name":"Get Balance","id":"1147ad64-d8cd-4555-83fd-9ae0f08af4b8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"Your_API_Key_Here","type":"text"},{"key":"x-app-id","value":"Your_App_ID_Here","type":"text"}],"url":"https://app.malipo.mw/api/v1/accounts/balance","description":"This endpoint retrieves the balance information for the account/application.
\n{\n \"status\": \"\",\n \"data\": {\n \"balance\": \"\",\n \"currency\": \"\"\n }\n}\n\nStartFragment
\nWhen the client raises a request to the server through an API, the client should know the feedback, whether it failed, passed or the request was wrong. HTTP status codes are a bunch of standardized codes which has various explanations in various scenarios. The server should always return the right status code.
\n200 OK - Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn't result in a creation.
\n201 Created - This status code indicates a successful response to a POST request that initiates a transaction request.EndFragment
\nFor a Disbursement Request, it confirms that the funds have been successfully sent to the Payee.
\nFor a Push Payment Request, it means the transaction request has been successfully initiated. However, the final success or failure of the transaction will be communicated through a callback request sent to the Merchant's webhook.
\n204 No Content - Response to a successful request that won't be returning a body (like a DELETE request)
\n304 Not Modified - Used when HTTP caching headers are in play
\n400 Bad Request - The request is malformed, such as if the body does not parse
\n401 Unauthorized - When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
\n403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource
\n404 Not Found - When a non-existent resource is requested
\n405 Method Not Allowed - When an HTTP method is being requested that isn't allowed for the authenticated user
\n410 Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
\n415 Unsupported Media Type - If incorrect content type was provided as part of the request
\n422 Unprocessable Entity - Used for validation errors
\n429 Too Many Requests - When a request is rejected due to rate limiting
\n500 Internal Server Error - This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server
\n503 Service Unavailable - The server is unable to handle the request for a service due to temporary maintenance
\nEndFragment
\n","_postman_id":"e3da6555-f24e-4e6b-ac7d-e5288b0ebbac"}],"event":[{"listen":"prerequest","script":{"id":"fd103385-a724-4a80-b8cb-49284c467956","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"55419c3e-55da-41d2-b259-3de93c17afe8","type":"text/javascript","exec":[""]}}],"variable":[{"key":"BASE_URL","value":"http://localhost:8000/api/v1","type":"string","disabled":true},{"key":"BASE_URL","value":"https://app.malipo.mw/api/v1","type":"string"},{"key":"APP_ID","value":"Your_App_ID_Here","type":"string"},{"key":"API_KEY","value":"Your_API_Key_Here","type":"string"}]}