Developer API

SwApp Payment API documentation for Ugandan integrations.

A Postman-style API reference hosted on the SwApp site: authenticate, validate accounts, collect funds, send payouts, check balances, and reconcile transaction status without leaving the domain.

Request API access View endpoints

OAuth 2.0 bearer tokens JSON REST requests Collections, payouts, validation, and status

9Published API operations

POSTJSON request pattern

UUIDRequestId for reconciliation

UGBuilt for Uganda payment workflows

Overview

Payment operations API for collections, payouts, and reconciliation.

The SwApp API is a JSON REST API for approved merchants and platforms that need payment services inside their own systems. It is designed around Uganda payment workflows, clear transaction references, and finance follow-up.

REST JSONRequests are sent as JSON in the body of POST messages.

Standard methodsValidate, collect, payout, balance, and status checks follow predictable patterns.

Provider abstractionClient systems do not need to know every provider-specific internal representation.

Reconciliation firstRequestId values tie transaction initiation to status checks and reports.

Authentication

Use merchant credentials to request an OAuth bearer token.

SwApp issues three integration credentials to an approved merchant: Client ID, API Key, and API Secret. The API Key and API Secret are used as Basic auth credentials on the token request. The returned bearer token is used on other payment API endpoints until it expires.

Protect bearer tokens.Any party holding a bearer token can access the associated resources. Store and transmit tokens securely.

Token request

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/token' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Basic {{base64_api_key_api_secret}}'

Request flow

Recommended integration sequence.

Request tokenYour system authenticates with API Key and API Secret.
Validate accountConfirm the customer or payee account before money moves.
Initiate collect or payoutSend the payment request with a unique RequestId.
Check statusUse the same RequestId for transaction status and reconciliation follow-up.

RequestId

Generate a unique UUID for transaction traceability.

Use a unique UUID for collection and payout requests. Keep it under 48 characters and store it in your system because it is the reference used for status checks and reconciliation.

Python UUID example

import uuid
RequestId = str(uuid.uuid4())

Endpoints

Published payment API operations.

These endpoints mirror the current SwApp Postman collection while keeping the integration reference on the SwApp site.

Headers used by bearer-token calls

After creating an access token, most payment API requests use the same bearer-token headers. Endpoint cards below focus on URL, request fields, body examples, and cURL.

Header	Value	Use
`Swapp-Client-ID`	`{{client_id}}`	Merchant client identifier. Used on most mobile money endpoints.
`Authorization`	`Bearer {{access_token}}`	OAuth bearer token returned by the Create Access Token request.
`Content-Type`	`application/json`	Required when sending a JSON request body.

POST Create Access Token Request an OAuth 2.0 bearer token before calling the mobile money endpoints. API Key and API Secret are used as the Basic auth username and password. Basic Details

Request an OAuth 2.0 bearer token before calling the mobile money endpoints. API Key and API Secret are used as the Basic auth username and password.

POSThttps://www.swapp.co.ug/apitest/mm/token

Token request headers

Header	Value
`Swapp-Client-ID`	`{{client_id}}`
`Authorization`	`Basic {{base64_api_key_api_secret}}`

Request fields

Name	Type	Required	Description
`api_key`	string	Yes	Issued to the merchant and used as the Basic auth username.
`api_secret`	string	Yes	Issued to the merchant and used as the Basic auth password.
`client_id`	string	Yes	Merchant client identifier sent in the Swapp-Client-ID header.

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/token' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Basic {{base64_api_key_api_secret}}'

POST Validate Customer Number Confirm customer or payee identity before initiating a mobile money request. Bearer Details

Confirm customer or payee identity before initiating a mobile money request.

POSThttps://www.swapp.co.ug/apitest/mm/validate

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Phone number without international code or leading zero, for example 772112233.
`Amount`	integer	Optional	Transaction value. When supplied, the response can include expected charges.
`Type`	enum	Optional	Use collect or payout. Defaults to collect where not supplied.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": 50000,
  "Type": "collect"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/validate' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": 50000,
  "Type": "collect"
}'

POST MoMo Deposit Validate Validate a mobile money deposit account before a deposit workflow is completed. Bearer Details

Validate a mobile money deposit account before a deposit workflow is completed.

POSThttps://www.swapp.co.ug/apitest/mm/momo_validate

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Phone number without international code or leading zero.
`Amount`	integer	Optional	Transaction value used to estimate charges where applicable.
`Type`	string	Yes	Use deposit for this validation path.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": 50000,
  "Type": "deposit"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/momo_validate' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": 50000,
  "Type": "deposit"
}'

POST Collection Collect funds from a customer and top up the merchant account on the SwApp platform. Bearer Details

Collect funds from a customer and top up the merchant account on the SwApp platform.

POSThttps://www.swapp.co.ug/apitest/mm/collect

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Customer phone number without international code or leading zero.
`Amount`	integer	Yes	Transaction amount.
`RequestId`	UUID string	Yes	Unique transaction reference generated by your system. Must be less than 48 characters.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": {{txn_amount}},
  "RequestId": "{{unique_request_id}}"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/collect' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": {{txn_amount}},
  "RequestId": "{{unique_request_id}}"
}'

POST Payout Send money from a merchant account to a payee account. Bearer Details

Send money from a merchant account to a payee account.

POSThttps://www.swapp.co.ug/apitest/mm/payout

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Payee phone number without international code or leading zero.
`Amount`	integer	Yes	Payout amount.
`RequestId`	UUID string	Yes	Unique reference for the payout, used later for status checks.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": {{txn_amount}},
  "RequestId": "{{unique_request_id}}"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/payout' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": {{txn_amount}},
  "RequestId": "{{unique_request_id}}"
}'

POST Transaction Status Check the status of a collection, payout, or related mobile money request using the original RequestId. Bearer Details

Check the status of a collection, payout, or related mobile money request using the original RequestId.

POSThttps://www.swapp.co.ug/apitest/mm/getstatus

Request fields

Name	Type	Required	Description
`RequestId`	UUID string	Yes	The same unique reference used in the original transaction request.

Sample body

{
  "RequestId": "{{unique_request_id}}"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/getstatus' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "RequestId": "{{unique_request_id}}"
}'

POST Get Account Balance Check the balance on the default account connected to the merchant. Bearer Details

Check the balance on the default account connected to the merchant.

POSThttps://www.swapp.co.ug/apitest/mm/balance

Request fields

No JSON body fields are required for this endpoint.

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/balance' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}'

POST FlatValidate Validate an account and flat amount through the published flat validation endpoint. Bearer Details

Validate an account and flat amount through the published flat validation endpoint.

POSThttps://www.swapp.co.ug/api/mm/flatvalidate

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Phone number without international code or leading zero.
`Amount`	string	Yes	Flat amount to validate.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": "2000"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/api/mm/flatvalidate' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": "2000"
}'

POST FlatPayout Initiate a flat payout using account, amount, and RequestId. Bearer Details

Initiate a flat payout using account, amount, and RequestId.

POSThttps://www.swapp.co.ug/apitest/mm/flatpayout

Request fields

Name	Type	Required	Description
`Account`	string	Yes	Payee phone number without international code or leading zero.
`Amount`	string	Yes	Flat payout amount.
`RequestId`	UUID string	Yes	Unique reference generated by your system.

Sample body

{
  "Account": "{{phone_number}}",
  "Amount": "2000",
  "RequestId": "{{unique_request_id}}"
}

cURL example

curl --location \
--request POST 'https://www.swapp.co.ug/apitest/mm/flatpayout' \
--header 'Swapp-Client-ID: {{client_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "Account": "{{phone_number}}",
  "Amount": "2000",
  "RequestId": "{{unique_request_id}}"
}'

Access and support

Need credentials or implementation help?

API credentials are issued by SwApp after onboarding. Share the collection, payout, validation, or reconciliation workflow you need, and the team will confirm the right setup before credentials are issued.

Request API access Payment API overview Postman API collection