{"info":{"_postman_id":"4e895684-16a9-4b3f-b9f3-08acca5f64b1","name":"Mobile Money API - SwApp","description":"

\n\n

The purpose of this api documentation enable all parties to implement SwApp Mobile Money APIs in a flexible, yet consistent manner. We are guided by the following principles:

Use of REST architectural principles.
Providing a set of well-defined objects that are abstracted from the underlying object representations held in the various mobile money systems. This allows an API client to construct an API message without requiring specific knowledge of the target server implementation.
Creation of a standard set of transaction types and other key enumerations, removing the need for developers to map for each and every API implementation.
Use of supplementary metadata and sub-types to enable use case and/or mobile money provider-specific properties to be conveyed where necessary.

The API is a JSON REST API that is used by merchants to access services on SwApp platform. The API exposes services that are used by e.g. online merchants for managing payments and other financial services. This document gives an overview of the structure of the API.

Authentication

There are two credentials used in the API.

Client ID
API Key and API Secret for Oauth 2.0

API Key and API will be issued to the merchant upon request from SwApp.

Oauth 2.0

The Open API uses Oauth 2.0 token for authentication of request. User will request an access token using Client Credential Grant according to RFC 6749. The token received is according to RFC 6750 Bearer Token.

Important: Any party in possession of a bearer token (a \"bearer\") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.

The API Key and API Secret are used in the basic authentication header when requesting the access token. The API key and secret are managed in the merchant portal.

The request authentication is set by setting the Authorization Header in the request such as :

curl --location --request POST 'https://www.swapp.co.ug/apitest/mm/token' \\\n--header 'Swapp-Client-ID: 37480908' \\\n--header 'Authorization: Basic NWXXXXXXXXXXXXX'\n\n

The received token has an expiry time. The same token can be used for transactions until it expires. A new token is requested by using the POST /token api in the same way as the initial token. The new token can be requested before the previous one has expired to avoid authentication failure due to an expired token.

The below sequence describes the flow for requesting a token and using the token in a request.

\n $\"Flow%20Diagram%20for%20accessing%20API\"$ \n\n

The merchant system requests an access token using the API Key and API Secret as authentication.
The SwApp platform authenticates credentials and responds with the access token.
Merchant system will use the access token for any request that is sent to the SwApp Platform, e.g. POST /validate
Validate Customer response will contain customer account details. Please verify the customer account before proceeding to make a payment.
POST /payout will initiate a payout request. The same token received it step 2 may be used depending on the validity period.
The Response will contain the status of the transaction issued in step 5 above.

RequestId

Format - UUID.

Unique Reference ID for the created request to collect or payout transaction. This ID is used, for example, to validate the status of the request. ‘Universal Unique ID’ for the transaction generated using any UUID id.

For Python, uuid can be generated as below:

import uuid\nRequestId = str(uuid.uuid4())\n\n

Other programming languages have similar modules for generating UUIDs

RequestId should be limited to less than 48 characters

API Methods

Request parameters should be passed as JSON data in the body of the POST message.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"20677093","collectionId":"4e895684-16a9-4b3f-b9f3-08acca5f64b1","publishedId":"2s8Z72UB6X","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2023-01-04T16:21:54.000Z"},"item":[{"name":"Create Access Token","id":"4bf7cdaf-39fe-415e-8b32-08d2adef9675","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{api_key}}"},{"key":"password","value":"{{api_secret}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"url":"https://www.swapp.co.ug/apitest/mm/token","description":"

Requests to the API should include an authorization token. To receive the token, send a token request with Basic authentication using API Access credentials (API Key / API Secret) as user ID/password pairs encoded using base64.

The returned response will contain the access token and the validity of the token.

\n","urlObject":{"protocol":"https","path":["apitest","mm","token"],"host":["www","swapp","co","ug"],"query":[],"variable":[]}},"response":[{"id":"95f759bd-c00c-47b5-9861-2a26565f2419","name":"Create Access Token","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"url":"https://www.swapp.co.ug/apitest/mm/token"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"4bf7cdaf-39fe-415e-8b32-08d2adef9675"},{"name":"Validate Customer Number","id":"900df3b3-6b6e-40e5-bfef-f7caeb039cc9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/validate","description":"

Validate Customer details so as to confirm identity before executing a Mobile Money Request. This is intended to limit errors such as sending to the wrong number during payout Requests

\n","urlObject":{"protocol":"https","path":["apitest","mm","validate"],"host":["www","swapp","co","ug"],"query":[{"disabled":true,"description":{"content":"

(Required) Phone number for the customer or payee. The number should be without international codes or the leading 0. For example 772112233

\n","type":"text/plain"},"key":"Account","value":"[string]"},{"disabled":true,"description":{"content":"

(Optional) Value for the transaction. If set, the response will return the expected charges on the transaction.

\n","type":"text/plain"},"key":"Amount","value":"[integer]"},{"disabled":true,"description":{"content":"

(Optional) Get correct charges for type of transaction. Default is 'collect'

\n","type":"text/plain"},"key":"Type","value":"enum {payout, collect}"}],"variable":[]}},"response":[{"id":"68c7641d-8e84-45e8-899b-14b36144f4ac","name":"Validate Customer Number","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/validate"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"900df3b3-6b6e-40e5-bfef-f7caeb039cc9"},{"name":"Collection","id":"22061c69-01ae-4020-9809-3def12e2f91e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\",\n \"Amount\": {{txn_amount}},\n \"RequestId\": \"{{unique_request_id}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/collect","description":"

Collect API allows the merchant to collect funds from a user and these funds will be topped up to the merchant account on Swapp Platform.

Bearer authentication is used with the token acquired from the token api call.

\n","urlObject":{"protocol":"https","path":["apitest","mm","collect"],"host":["www","swapp","co","ug"],"query":[{"disabled":true,"description":{"content":"

(Required) Phone number for the customer or payee. The number should be without international codes or the leading 0. For example 772112233

\n","type":"text/plain"},"key":"Account","value":"[string]"},{"disabled":true,"description":{"content":"

(Required) Value for the transaction.

\n","type":"text/plain"},"key":"Amount","value":"[integer]"},{"disabled":true,"description":{"content":"

(Required) A unique id generated by the users to identify the transaction. Must be UUID format as described in introduction. Must be less than 48 characters long.

\n","type":"text/plain"},"key":"RequestId","value":"[string] UUID"}],"variable":[]}},"response":[{"id":"4b298c65-0beb-40bc-b9ac-b6b619a25a53","name":"Collection","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\",\n \"Amount\": {{txn_amount}},\n \"RequestId\": {{unique_request_id}}\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/collect"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"22061c69-01ae-4020-9809-3def12e2f91e"},{"name":"Payout","id":"6639f81c-706b-41c3-af9e-e7ff3d0e236b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\",\n \"Amount\": {{txn_amount}},\n \"RequestId\": \"{{unique_request_id}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/payout","description":"

Payout operation is used to send an amount from the merchants’s account to a payee account.

\n","urlObject":{"protocol":"https","path":["apitest","mm","payout"],"host":["www","swapp","co","ug"],"query":[{"disabled":true,"description":{"content":"

(Required) Phone number for the customer or payee. The number should be without international codes or the leading 0. For example 772112233

\n","type":"text/plain"},"key":"Account","value":"[string]"},{"disabled":true,"description":{"content":"

(Required) Value for the transaction.

\n","type":"text/plain"},"key":"Amount","value":"[integer]"},{"disabled":true,"description":{"content":"

(Required) A unique id generated by the users to identify the transaction. Must be UUID format as described in introduction. Must be less than 48 characters long.

\n","type":"text/plain"},"key":"RequestId","value":"[string] UUID"}],"variable":[]}},"response":[{"id":"a0c9c17e-d709-4bb3-b721-f7da6b07d57d","name":"Payout","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Account\": \"{{phone_number}}\",\n \"Amount\": {{txn_amount}},\n \"RequestId\": {{unique_request_id}}\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://www.swapp.co.ug/apitest/mm/payout","protocol":"https","host":["www","swapp","co","ug"],"path":["apitest","mm","payout"],"query":[{"key":"Account","value":"774123456","type":"text","disabled":true}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"6639f81c-706b-41c3-af9e-e7ff3d0e236b"},{"name":"Transaction Status","id":"5735ef25-27f5-42b6-87fa-440ec44e74cf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"RequestId\": \"{{unique_request_id}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://www.swapp.co.ug/apitest/mm/getstatus","description":"

This operation is used to get the status of a request. The RequestId that was passed in the post of the transaction is used as reference to the request.

\n","urlObject":{"protocol":"https","path":["apitest","mm","getstatus"],"host":["www","swapp","co","ug"],"query":[{"disabled":true,"description":{"content":"

(Required) A unique id of the related payment as set in the Payment Initiation Request

\n","type":"text/plain"},"key":"RequestId","value":"[string] UUID"}],"variable":[]}},"response":[{"id":"2c2409eb-1a17-498e-aaae-d45aebebd062","name":"Transaction Status","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n\"RequestId\": {{unique_request_id}}\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://www.swapp.co.ug/apitest/mm/getstatus","protocol":"https","host":["www","swapp","co","ug"],"path":["apitest","mm","getstatus"],"query":[{"key":"Account","value":"774123456","type":"text","disabled":true}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"5735ef25-27f5-42b6-87fa-440ec44e74cf"},{"name":"Get Account Balance","id":"084ed67b-21c1-4de7-a8d5-5542f029607e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"url":"https://www.swapp.co.ug/apitest/mm/balance","description":"

Get balance request is used to check the balance on the default account connected to the Merchant.

\n","urlObject":{"protocol":"https","path":["apitest","mm","balance"],"host":["www","swapp","co","ug"],"query":[],"variable":[]}},"response":[{"id":"2b488766-603c-447e-9c02-5b9c76b8639a","name":"Get Account Balance","originalRequest":{"method":"POST","header":[{"key":"Swapp-Client-ID","value":"{{client_id}}","type":"text"}],"url":"https://www.swapp.co.ug/apitest/mm/balance"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"084ed67b-21c1-4de7-a8d5-5542f029607e"}]}