API Documentation | Ssentezo Wallet

Introduction

Ssentezo Wallet is a comprehensive payment platform that enables businesses and developers to collect or deliver payments through mobile money, Visa and Mastercard, and bank accounts.

Use the REST API to collect and disburse mobile money, accept Visa and Mastercard, or push funds to a bank account. Card payments open a hosted checkout page, and a successful payment is credited to your wallet.

Environments

LIVE Environment

Real money transactions. Actual money is credited and debited from phone numbers during operations.

https://wallet.ssentezo.com/api

Register for LIVE →

SANDBOX Environment

Testing environment with no real money transactions. Perfect for development and testing.

https://devwallet.ssentezo.com/api

Register for SANDBOX →

Note: Functionality in LIVE and SANDBOX modes is exactly the same. Only the endpoint URL changes between environments.

Authentication

The API uses HTTP Basic Authentication. You'll need valid API credentials which can be generated from the API Access menu in your Wallet Account.

Important: All requests must contain the Authorization header with base64 encoded credentials.

Authentication Examples

PHP

<?php
// Your API credentials
$apiUser = 'your_api_user';
$apiKey = 'your_api_key';

// Encode credentials to base64
$encodedString = base64_encode($apiUser . ':' . $apiKey);

// Example using Guzzle HTTP Client (install with: composer require guzzlehttp/guzzle)
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client();

// Example request configuration
$response = $client->post('https://wallet.ssentezo.com/api/acc_balance', [
    'headers' => [
        'Authorization' => 'Basic ' . $encodedString,
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'currency' => 'UGX'
    ]
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

JavaScript

// Your API credentials
const apiUser = 'your_api_user';
const apiKey = 'your_api_key';

// Encode credentials to base64
const encodedString = btoa(`${apiUser}:${apiKey}`);

// Make API request
async function checkBalance() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/acc_balance', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${encodedString}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                currency: 'UGX'
            })
        });

        const data = await response.json();
        console.log(data);
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}

checkBalance();

Python

import requests
import base64
import json

# Your API credentials
api_user = 'your_api_user'
api_key = 'your_api_key'

# Encode credentials to base64
credentials = f"{api_user}:{api_key}"
encoded_string = base64.b64encode(credentials.encode()).decode()

# Set up headers
headers = {
    'Authorization': f'Basic {encoded_string}',
    'Content-Type': 'application/json'
}

# Make API request
def check_balance():
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/acc_balance',
            headers=headers,
            json={'currency': 'UGX'}
        )
        
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

# Check balance
balance = check_balance()
print(balance)

API Limits

No negative figures, exponential figures (e.g., e100), or characters in amounts

Transactions between UGX 500 to UGX 7,000,000

Charges apply as per your Ssentezo agreement

Supported Currency

UG

Uganda Shillings

UGX

Supported

HTTP Response Codes

Status Code	Interpretation
202	Succeeded Transaction
400	Failed Transaction
401	No Authorization Header
403	Invalid Credentials
422	Unprocessable Entity
500	Internal Server Error

Transaction Statuses

PENDING

Transaction still pending. All transactions begin from this state.

SUCCEEDED

Transaction completed successfully.

FAILED

Transaction failed to complete.

INDETERMINATE

Status not yet determined. Can take up to 48hrs.

API Response Format

✅ Successful Response

JSON

{
  "response": "OK",
  "data": {
    "amount": 1834665,
    "formatted": "1,834,665",
    "currency": "UGX"
  }
}

❌ Error Response

JSON

{
  "response": "ERROR",
  "error": {
    "message": "The currency field is required."
  }
}

Rate Limiting

To ensure the stability and security of our API, we implement rate limiting on all endpoints. Rate limiting protects against abuse, prevents system overload, and ensures fair usage across all clients.

Security Measure

For security reasons, we do not disclose specific rate limits. Limits are dynamically adjusted based on usage patterns and endpoint sensitivity.

Why We Implement Rate Limiting

Security Protection

Prevents malicious attacks, brute force attempts, and unauthorized access patterns

System Stability

Maintains consistent performance and prevents system overload during peak usage

Fair Usage

Ensures equitable access to API resources for all clients and prevents monopolization

Compliance

Meets financial industry standards and regulatory requirements for secure API access

Rate Limit Exceeded Response

When you exceed the rate limit, the API will return a structured error response with HTTP status code 429.

❌ Rate Limit Response

JSON

{
  "response": "ERROR",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. You have exceeded the rate limit."
  }
}

📋 Response Details

HTTP Status: 429 Too Many Requests

Error Code: RATE_LIMIT_EXCEEDED

Response Format: Consistent with all API error responses

Best Practices

✅ Recommended Approaches

Implement Exponential Backoff

When you receive a 429 response, wait progressively longer between retries (e.g., 1s, 2s, 4s, 8s).

Cache Responses

Cache API responses where appropriate (e.g., bank lists, account balances) to reduce API calls.

Batch Operations

Group multiple operations together when possible rather than making individual API calls.

❌ Avoid These Patterns

Aggressive Polling

Don't repeatedly check transaction status in tight loops. Use callbacks or reasonable intervals.

Immediate Retries

Don't immediately retry after a 429 response. This will only extend the rate limiting period.

Parallel Requests

Avoid making multiple parallel requests to the same endpoint, especially for financial operations.

Check Account Balance

POST /api/acc_balance

Get your current wallet balance for a specific currency.

Parameters

Parameter	Type	Required	Description
currency	String	Required	Currency code (e.g., "UGX")

Request Example

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

// Example request configuration
$response = $client->post('https://wallet.ssentezo.com/api/acc_balance', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'currency' => 'UGX',
    ],
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

Request Example

JavaScript

const response = await fetch('https://wallet.ssentezo.com/api/acc_balance', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${btoa('api_user:api_key')}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        currency: 'UGX'
    })
});

const result = await response.json();
console.log(result);

Request Example

Python

import requests
import base64

credentials = base64.b64encode('api_user:api_key'.encode()).decode()

response = requests.post(
    'https://wallet.ssentezo.com/api/acc_balance',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json={'currency': 'UGX'}
)

result = response.json()
print(result)

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "amount": 1834665,
    "formatted": "1,834,665",
    "currency": "UGX"
  }
}

❌ Error Response

JSON

{
  "response": "ERROR",
  "error": {
    "message": "The currency field is required."
  }
}

MSISDN/Phone Number Verification

POST /api/msisdn-verification

Verify the name associated with a phone number before processing transactions.

Parameters

Parameter	Type	Required	Description
msisdn	String	Required	Phone number in international format (e.g., "256709920188")

Request Example

PHP

<?php
use GuzzleHttp\Client;

$requestBody = [
    'msisdn' => '256709920188',
];

$client = new Client();

// Example request configuration
$response = $client->post('https://wallet.ssentezo.com/api/msisdn-verification', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

Request Example

JavaScript

const requestBody = {
    msisdn: '256709920188'
};

async function verifyMsisdn() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/msisdn-verification', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(requestBody)
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

verifyMsisdn();

Request Example

Python

import requests
import base64

request_body = {
    'msisdn': '256709920188'
}

def verify_msisdn():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/msisdn-verification',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            },
            json=request_body
        )
        
        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

verify_msisdn()

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "msisdn": "256712345678",
    "FirstName": "John",
    "Surname": "Doe"
  }
}

❌ Error Response (Invalid Format)

JSON

{
  "response": "ERROR",
  "error": {
    "message": "The msisdn field format is invalid."
  }
}

❌ Error Response (Verification Failed)

JSON

{
  "response": "ERROR",
  "error": {
    "message": "Failed to verify the name of the holder of the MSISDN"
  }
}

Withdraw Funds

POST /api/withdraw

Send money from your wallet to a mobile money account.

Parameters

Parameter	Type	Required	Description
externalReference	String	Required	Unique reference (max 250 chars)
msisdn	String	Required	Phone number in international format
amount	Number	Required	Amount between 500 and 7,000,000
currency	String	Required	Currency code (e.g., "UGX")
reason	String	Required	Transaction reason/description
name	String	Optional	Recipient name
success_callback	String	Optional	Success callback URL
failure_callback	String	Optional	Failure callback URL

Request Example

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'externalReference' => 'unique-ref-' . time(),
    'msisdn' => '256770691484',
    'amount' => 2000,
    'currency' => 'UGX',
    'reason' => 'Payment for services',
    'name' => 'John Doe',
    'success_callback' => 'https://yourapp.com/success-callback',
    'failure_callback' => 'https://yourapp.com/failure-callback',
];


// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/withdraw', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...

?>

Request Example

JavaScript

const requestBody = {
    externalReference: `unique-ref-${Date.now()}`,
    msisdn: '256770691484',
    amount: 2000,
    currency: 'UGX',
    reason: 'Payment for services',
    name: 'John Doe',
    success_callback: 'https://yourapp.com/success-callback',
    failure_callback: 'https://yourapp.com/failure-callback'
};

const response = await fetch('https://wallet.ssentezo.com/api/withdraw', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${btoa('api_user:api_key')}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
});

const result = await response.json();

Request Example

Python

import requests
import base64
import time

request_body = {
    'externalReference': f'unique-ref-{int(time.time())}',
    'msisdn': '256770691484',
    'amount': 2000,
    'currency': 'UGX',
    'reason': 'Payment for services',
    'name': 'John Doe',
    'success_callback': 'https://yourapp.com/success-callback',
    'failure_callback': 'https://yourapp.com/failure-callback'
}

credentials = base64.b64encode('api_user:api_key'.encode()).decode()

response = requests.post(
    'https://wallet.ssentezo.com/api/withdraw',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json=request_body
)

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "PENDING",
    "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
    "financialTransactionId": "b997c60c6f445185fcd9a3a595533734"
  }
}

❌ Error Response

JSON

{
  "response": "ERROR",
  "error": {
    "code": "UPPER_CEILING_BREACH",
    "message": "Maximum transaction amount is UGX 7,000,000"
  }
}

Parameter Descriptions

externalReference: Unique identifier for your transaction (max 250 characters). Must be unique across all transactions.

msisdn: Phone number in international format (e.g., 256770691484)

amount: Amount without formatting or non-numeric characters. Must be between UGX 500 - 7,000,000

financialTransactionId: Unique ID from the network provider (MTN/Airtel) for tracking

Collect Money (Deposit)

POST /api/deposit

Collect money from a mobile money account into your wallet.

Parameters

Parameter	Type	Required	Description
externalReference	String	Required	Unique reference (max 250 chars)
msisdn	String	Required	Phone number to collect from
amount	Number	Required	Amount between 500 and 7,000,000
currency	String	Required	Currency code (e.g., "UGX")
reason	String	Required	Collection reason
name	String	Optional	Payer name
success_callback	String	Optional	Success callback URL
failure_callback	String	Optional	Failure callback URL

Request Example

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'externalReference' => 'unique-ref-' . time(),
    'amount' => 1000,
    'msisdn' => '256770691484',
    'reason' => 'Payment for services',
    'currency' => 'UGX',
    'name' => 'John Doe',
    'success_callback' => 'https://yourapp.com/success-callback',
    'failure_callback' => 'https://yourapp.com/failure-callback',
];

// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/deposit', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

Request Example

JavaScript

const requestBody = {
    externalReference: `unique-ref-${Date.now()}`,
    amount: 1000,
    msisdn: '256770691484',
    reason: 'Payment for services',
    currency: 'UGX',
    name: 'John Doe',
    success_callback: 'https://yourapp.com/success-callback',
    failure_callback: 'https://yourapp.com/failure-callback'
};

async function collectMoney() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/deposit', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(requestBody)
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

collectMoney();

Request Example

Python

import requests
import base64
import time

request_body = {
    'externalReference': f'unique-ref-{int(time.time())}',
    'amount': 1000,
    'msisdn': '256770691484',
    'reason': 'Payment for services',
    'currency': 'UGX',
    'name': 'John Doe',
    'success_callback': 'https://yourapp.com/success-callback',
    'failure_callback': 'https://yourapp.com/failure-callback'
}

def collect_money():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/deposit',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            },
            json=request_body
        )
        
        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

collect_money()

Example Request Body

JSON

{
  "externalReference": "unique-ref-123456",
  "amount": 1000,
  "msisdn": "256770691484",
  "reason": "Payment for services",
  "currency": "UGX",
  "name": "John Doe",
  "success_callback": "https://yourapp.com/success-callback",
  "failure_callback": "https://yourapp.com/failure-callback"
}

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "PENDING",
    "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
    "financialTransactionId": "b997c60c6f445185fcd9a3a595533734"
  }
}

❌ Validation Error

JSON

{
  "response": "ERROR",
  "error": {
    "message": "The given data was invalid.",
    "errors": {
      "amount": ["The amount field must be at least 500."],
      "msisdn": ["The msisdn field is required."],
      "externalReference": ["The external reference has already been taken."]
    }
  }
}

Note: A PENDING status with HTTP 202 means the transaction has been initiated and the payer must enter their Mobile Money PIN. The callback endpoint will be called once the transaction completes.

Check Transaction Status

POST /api/get_status/{externalReference}

Check the current status of a transaction using your external reference.

URL Parameters

Parameter	Type	Required	Description
externalReference	String	Required	The external reference used when creating the transaction

Request Example

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$externalReference = 'your-external-reference-here';

// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/get_status/' . $externalReference, [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
*/
?>

Request Example

JavaScript

const externalReference = 'your-external-reference-here';

async function checkTransactionStatus(externalReference) {
    try {
        const response = await fetch(`https://wallet.ssentezo.com/api/get_status/${externalReference}`, {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            }
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

checkTransactionStatus(externalReference);

Request Example

Python

import requests
import base64

def check_transaction_status(external_reference):
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            f'https://wallet.ssentezo.com/api/get_status/{external_reference}',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            }
        )
        
        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

# Example usage
external_reference = 'your-external-reference-here'
check_transaction_status(external_reference)

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "SUCCEEDED",
    "ssentezoWalletReference": "3181ead4-eff9-4b9b-b926-53b41e632ca5",
    "externalReference": "rfg54rj59033w4672326hi45h6j6456",
    "financialTransactionId": "QkK0UVtkMlCZN1ZEuKVv4NU5l2sFA1uO82fb7ef5f6a2530bc5c2118b34620b5a",
    "amount": 3000,
    "reason": "Sending money to someone",
    "currency": "UGX",
    "msisdn": "256770691484",
    "transactionTime": "2024-04-24T16:24:58.000000Z"
  }
}

Transaction Status Notifications

If you want to be notified immediately when a transaction status changes from PENDING to either SUCCEEDED or FAILED, you can specify callback URLs in your deposit/withdraw requests.

Callback Parameters

success_callback: URL called when transaction succeeds
failure_callback: URL called when transaction fails

Sample Callback Data

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "SUCCEEDED",
    "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
    "externalReference": "16011650463271",
    "financialTransactionId": "f245ddac-1622-4dad-9a94-4e289bb6b8a4-f245ddac-1622-4dad-9a94-4e289bb6b8a4"
  }
}

Note 1: Ensure your callback URLs are publicly accessible and resolve within 5 seconds, otherwise the request will timeout.

Note 2: Callback endpoints should not require authentication as our system needs unrestricted access to notify you.

Transaction History

POST /api/transaction-history

Retrieve a paginated list of your organization's transactions for a single day or a date range, with optional filters for status, transaction type, and search.

Note: You must supply either date on its own, or both startDate and endDate together.

Parameters

Parameter	Type	Required	Description
date	String	Conditional	A single date in `YYYY-MM-DD` format. Use this instead of a date range.
startDate	String	Conditional	Start of the date range (`YYYY-MM-DD`). Required together with `endDate` when `date` is not used.
endDate	String	Conditional	End of the date range (`YYYY-MM-DD`), must be on or after `startDate`.
transactionStatus	String	Optional	Filter by status: `SUCCEEDED`, `FAILED`, or `PENDING`. Omit to return all statuses.
transactionType	String	Optional	Filter by type: `COLLECTION` or `DISBURSEMENT`.
primaryOnly	Boolean	Optional	When `true`, excludes charge entries and returns only primary transactions. Defaults to `false` (all transactions).
search	String	Optional	Free-text search across the transaction reference, amount, charges, reason, external reference, and MSISDN.
page	Number	Optional	Page number to retrieve. Defaults to `1`.
perPage	Number	Optional	Number of records per page (max `200`). Defaults to `50`.

Code Examples

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'startDate' => '2026-08-01',
    'endDate' => '2026-08-04',
    'transactionStatus' => 'SUCCEEDED',
    'transactionType' => 'COLLECTION',
    'perPage' => 50,
    'page' => 1,
];

// Example request configuration
$response = $client->post('https://wallet.ssentezo.com/api/transaction-history', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// $transactions = $result['data']['transactions'];
// Process your $result here...
?>

JavaScript

const requestBody = {
    startDate: '2026-08-01',
    endDate: '2026-08-04',
    transactionStatus: 'SUCCEEDED',
    transactionType: 'COLLECTION',
    perPage: 50,
    page: 1
};

async function getTransactionHistory() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/transaction-history', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(requestBody)
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

getTransactionHistory();

Python

import requests
import base64

request_body = {
    'startDate': '2026-08-01',
    'endDate': '2026-08-04',
    'transactionStatus': 'SUCCEEDED',
    'transactionType': 'COLLECTION',
    'perPage': 50,
    'page': 1
}

def get_transaction_history():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()

    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/transaction-history',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            },
            json=request_body
        )

        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

get_transaction_history()

Request Example

JSON

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-04",
  "transactionStatus": "SUCCEEDED",
  "transactionType": "COLLECTION",
  "perPage": 50,
  "page": 1
}

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactions": [
      {
        "ssentezoWalletReference": "593a7bf1-9581-484a-ba6e-e71f4f528bfd",
        "externalReference": "c734d323-8c1c-4160-8649-4df22443aa57",
        "transactionStatus": "SUCCEEDED",
        "transactionType": "COLLECTION",
        "isCharge": false,
        "amount": 5000,
        "charges": 100,
        "reason": "Payment for order #4521",
        "currency": "UGX",
        "msisdn": "256709920188",
        "financialTransactionId": "MP240730.1234.A56789",
        "transactionTime": "2026-08-01T09:14:22.000000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "perPage": 50,
      "total": 128,
      "lastPage": 3
    }
  }
}

❌ Error Response

JSON

{
  "response": "ERROR",
  "error": {
    "message": "The given data was invalid.",
    "errors": {
      "date": [
        "Provide either a \"date\" or both \"startDate\" and \"endDate\"."
      ]
    }
  }
}

Card Collection (Visa / Mastercard)

Accept Visa and Mastercard payments through a hosted checkout. Call the API to start a payment, then redirect the customer's browser to the checkoutUrl in the response. Card details are entered on Pegasus's secure page, never on your website. A successful payment is credited to your Ssentezo wallet. Every organization is on a card collection policy of 5% of the amount, for payments from UGX 500 to UGX 7,000,000.

1. Initiate a card collection

POST /api/card/collect

Creates a pending collection and returns the hosted checkout URL. Redirect the customer there immediately.

Parameter	Type	Required	Description
externalReference	String	Required	Your unique reference (max 255 characters)
amount	Number	Required	Amount in UGX. Minimum 500
currency	String	Required	Currency code. Use UGX
reason	String	Required	What the customer is paying for
name	String	Required	Cardholder name
email	String	Required	Cardholder email
success_callback	String	Optional	URL we POST when the payment succeeds
failure_callback	String	Optional	URL we POST when the payment fails
redirect_url	String	Optional	Where the customer's browser goes after a successful payment

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'externalReference' => 'order-4521',
    'amount' => 10000,
    'currency' => 'UGX',
    'reason' => 'Payment for order 4521',
    'name' => 'Jane Nakato',
    'email' => 'jane@example.com',
    'success_callback' => 'https://yourapp.com/payments/success',
    'failure_callback' => 'https://yourapp.com/payments/failure',
    'redirect_url' => 'https://yourapp.com/orders/4521/paid',
];

$response = $client->post('https://wallet.ssentezo.com/api/card/collect', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

$result = json_decode($response->getBody(), true);
$checkoutUrl = $result['data']['checkoutUrl'];
// Redirect the customer's browser to $checkoutUrl
?>

JavaScript

const requestBody = {
    externalReference: 'order-4521',
    amount: 10000,
    currency: 'UGX',
    reason: 'Payment for order 4521',
    name: 'Jane Nakato',
    email: 'jane@example.com',
    success_callback: 'https://yourapp.com/payments/success',
    failure_callback: 'https://yourapp.com/payments/failure',
    redirect_url: 'https://yourapp.com/orders/4521/paid'
};

async function collectByCard() {
    const response = await fetch('https://wallet.ssentezo.com/api/card/collect', {
        method: 'POST',
        headers: {
            'Authorization': `Basic ${btoa('api_user:api_key')}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestBody)
    });

    const result = await response.json();
    window.location.href = result.data.checkoutUrl;
}

collectByCard();

Python

import requests
import base64

request_body = {
    'externalReference': 'order-4521',
    'amount': 10000,
    'currency': 'UGX',
    'reason': 'Payment for order 4521',
    'name': 'Jane Nakato',
    'email': 'jane@example.com',
    'success_callback': 'https://yourapp.com/payments/success',
    'failure_callback': 'https://yourapp.com/payments/failure',
    'redirect_url': 'https://yourapp.com/orders/4521/paid',
}

def collect_by_card():
    credentials = base64.b64encode(b'api_user:api_key').decode()
    response = requests.post(
        'https://wallet.ssentezo.com/api/card/collect',
        headers={
            'Authorization': f'Basic {credentials}',
            'Content-Type': 'application/json',
        },
        json=request_body,
    )
    result = response.json()
    return result['data']['checkoutUrl']

print(collect_by_card())

Success response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "PENDING",
    "ssentezoWalletReference": "21537d54-bcd1-44a5-8614-717e093483ac",
    "externalReference": "order-4521",
    "checkoutUrl": "https://wallet.ssentezo.com/pegpay/card/checkout/21537d54-bcd1-44a5-8614-717e093483ac"
  }
}

Send the customer's browser to checkoutUrl. Check the result with Transaction Status using your externalReference, or wait for the callback.

• Minimum amount is UGX 500. Maximum is UGX 7,000,000. The service policy fee is 5%.
• success_callback and failure_callback are server notifications. redirect_url is where the customer's browser returns after a successful payment.
• Do not collect card numbers, expiry dates, or security codes on your own site.

Payment links

You can also collect cards without an API call. Create a payment link in the merchant dashboard and send the customer to it.

Create a card payment link

In the merchant dashboard, open Payment Links and create a link with Pay via set to Card (Visa / MasterCard).

Field	Required	Description
Name	Required	Title shown to the customer
Description	Required	What the customer is paying for
Pay via	Required	Card (Visa / MasterCard)
Amount	Optional	Fixed amount in UGX. Leave empty to let the customer enter it. Minimum UGX 500.
Redirect URL	Optional	Where to send the customer after a successful payment

2. Send the customer to the link

Copy the payment link from the dashboard, or build it from the link value. A card link opened at this address goes to the card checkout.

URL

https://wallet.ssentezo.com/merchants/collections/pay/{link_value}

HTML

<a href="https://wallet.ssentezo.com/merchants/collections/pay/YOUR_LINK_VALUE">
    Pay with Visa or Mastercard
</a>

3. Customer checkout

The customer completes these steps on the payment page:

Enters first name, last name, and email. If the link has no fixed amount, they also enter the amount.
Ssentezo redirects the browser to the hosted card page.
The customer enters the card number, expiry, and security code. A 3-D Secure card may also ask for a one-time password from the issuing bank.
On success, the collection is credited to your wallet. If you set a redirect URL, the customer is sent there. A failed payment stays on the result page and is not credited.

Settled payments

• Minimum amount is UGX 500.
• The service policy fee is 5% on amounts from UGX 500 to UGX 7,000,000.
• Settled card collections appear in your dashboard and in Transaction History as type COLLECTION.
• Do not collect card numbers, expiry dates, or security codes on your own site.

Bank Transfer (Push to Bank)

Push money from your wallet to a Ugandan bank account. All three endpoints use the same Basic authentication as the rest of the API. A transfer stays PENDING until you check the status and receive SUCCEEDED or FAILED.

1. Get Banks List

Retrieve supported banks and their IDs

2. Request Transfer

Initiate the bank transfer

3. Check Status

Confirm SUCCEEDED, FAILED, or PENDING

1. Get Supported Banks

POST /api/push-to-bank/get-banks

This endpoint requires no parameters and returns a list of supported banks.

Response Example

JSON

{
  "response": "OK",
  "data": {
    "banks": [
      {
        "id": 3,
        "bank_name": "Equity",
        "address": "Church House",
        "swift_code": "QW2456"
      },
      {
        "id": 4,
        "bank_name": "Stanbic Bank",
        "address": "Church House",
        "swift_code": "QW2456"
      },
      {
        "id": 5,
        "bank_name": "Housing Finance Bank",
        "address": "Ntinda",
        "swift_code": "QWE34E"
      }
    ]
  }
}

Code Examples

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/push-to-bank/get-banks', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
]);

// Handle the response
$result = json_decode($response->getBody(), true);

// Extract banks list
// $banks = $result['data']['banks'];
// Process your $banks here...

?>

JavaScript

async function getBanks() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/push-to-bank/get-banks', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            }
        });

        const result = await response.json();
        const banks = result.data.banks;
        console.log(banks);
        return banks;
    } catch (error) {
        console.error('Error:', error);
    }
}

getBanks();

Python

import requests
import base64

def get_banks():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/push-to-bank/get-banks',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            }
        )
        
        result = response.json()
        banks = result['data']['banks']
        print(banks)
        return banks
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

get_banks()

2. Request Bank Transfer

POST /api/push-to-bank/request-bank-transfer

Transfer money from your wallet to a bank account.

Parameters

Parameter	Type	Required	Description
external_reference	String	Required	Unique transaction identifier
bank_id	Number	Required	Bank ID from get-banks endpoint
account_name	String	Required	Bank account holder name
account_number	String	Required	Bank account number
amount	Number	Required	Amount from UGX 2,500 to UGX 50,000,000
reason	String	Optional	Transaction narration (2–255 characters when sent)

Code Examples

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'external_reference' => 'c734d323-8c1c-4160-8649-4df22443aa57',
    'bank_id' => 3,
    'account_name' => 'John Doe',
    'account_number' => '044653389534563',
    'amount' => '50000',
    'reason' => 'Pushing my money to the bank',
];

// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/push-to-bank/request-bank-transfer', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

JavaScript

const requestBody = {
    external_reference: 'c734d323-8c1c-4160-8649-4df22443aa57',
    bank_id: 3,
    account_name: 'John Doe',
    account_number: '044653389534563',
    amount: '50000',
    reason: 'Pushing my money to the bank'
};

async function requestBankTransfer() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/push-to-bank/request-bank-transfer', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(requestBody)
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

requestBankTransfer();

Python

import requests
import base64

request_body = {
    'external_reference': 'c734d323-8c1c-4160-8649-4df22443aa57',
    'bank_id': 3,
    'account_name': 'John Doe',
    'account_number': '044653389534563',
    'amount': '50000',
    'reason': 'Pushing my money to the bank'
}

def request_bank_transfer():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/push-to-bank/request-bank-transfer',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            },
            json=request_body
        )
        
        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

request_bank_transfer()

Request Example

JSON

{
  "external_reference": "c734d323-8c1c-4160-8649-4df22443aa57",
  "bank_id": 3,
  "account_name": "John Doe",
  "account_number": "044653389534563",
  "amount": "50000",
  "reason": "Pushing my money to the bank"
}

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "PENDING",
    "ssentezoWalletReference": "21537d54-bcd1-44a5-8614-717e093483ac",
    "externalReference": "82c7d1d6-850b-4e14-a0b7-5379058b17be"
  }
}

3. Check Bank Transfer Status

POST /api/push-to-bank/check-bank-transfer-status

Code Examples

PHP

<?php
use GuzzleHttp\Client;

$client = new Client();

$requestBody = [
    'external_reference' => 'c734d323-8c1c-4160-8649-4df22443aa57',
];

// Example request configuration

$response = $client->post('https://wallet.ssentezo.com/api/push-to-bank/check-bank-transfer-status', [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode('your_api_user:your_api_key'),
        'Content-Type' => 'application/json',
    ],
    'json' => $requestBody,
]);

// Handle the response
$result = json_decode($response->getBody(), true);
// Process your $result here...
?>

JavaScript

const requestBody = {
    external_reference: 'c734d323-8c1c-4160-8649-4df22443aa57'
};

async function checkBankTransferStatus() {
    try {
        const response = await fetch('https://wallet.ssentezo.com/api/push-to-bank/check-bank-transfer-status', {
            method: 'POST',
            headers: {
                'Authorization': `Basic ${btoa('api_user:api_key')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(requestBody)
        });

        const result = await response.json();
        console.log(result);
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
}

checkBankTransferStatus();

Python

import requests
import base64

request_body = {
    'external_reference': 'c734d323-8c1c-4160-8649-4df22443aa57'
}

def check_bank_transfer_status():
    credentials = base64.b64encode('api_user:api_key'.encode()).decode()
    
    try:
        response = requests.post(
            'https://wallet.ssentezo.com/api/push-to-bank/check-bank-transfer-status',
            headers={
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            },
            json=request_body
        )
        
        result = response.json()
        print(result)
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

check_bank_transfer_status()

Request Example

JSON

{
  "external_reference": "c734d323-8c1c-4160-8649-4df22443aa57"
}

✅ Success Response

JSON

{
  "response": "OK",
  "data": {
    "transactionStatus": "SUCCEEDED",
    "ssentezoWalletReference": "51c3d7b3-e70a-4016-8839-fe27a5c610fd",
    "externalReference": "c734d323-8c1c-4160-8649-4df22443aa57",
    "amount": 85000,
    "transactionTime": "2024-09-30T12:40:48.000000Z"
  }
}

⚠️ Important Notes

• Transfers are from UGX 2,500 to UGX 50,000,000
• The flat fee is UGX 5,000 up to 250,000; 6,000 up to 500,000; 9,000 up to 1,000,000; 13,500 up to 2,000,000; and 16,500 up to 50,000,000
• Bank transfers may take longer to process than mobile money transactions
• Always check the transfer status before marking transactions as complete

Ssentezo Wallet API 🚀

Introduction

Environments

LIVE Environment

SANDBOX Environment

Authentication

Authentication Examples

API Limits

Supported Currency

HTTP Response Codes

Transaction Statuses

API Response Format

✅ Successful Response

❌ Error Response

Rate Limiting

Why We Implement Rate Limiting

Security Protection

System Stability

Fair Usage

Compliance

Rate Limit Exceeded Response

❌ Rate Limit Response

📋 Response Details

Best Practices

✅ Recommended Approaches

Implement Exponential Backoff

Cache Responses

Batch Operations

❌ Avoid These Patterns

Aggressive Polling

Immediate Retries

Parallel Requests

Check Account Balance

Parameters

Request Example

Request Example

Request Example

✅ Success Response

❌ Error Response

MSISDN/Phone Number Verification

Parameters

Request Example

Request Example

Request Example

✅ Success Response

❌ Error Response (Invalid Format)

❌ Error Response (Verification Failed)

Withdraw Funds

Parameters

Request Example

Request Example

Request Example

✅ Success Response

❌ Error Response

Parameter Descriptions

Collect Money (Deposit)

Parameters

Request Example

Request Example

Request Example

Example Request Body

✅ Success Response

❌ Validation Error

Check Transaction Status

URL Parameters

Request Example

Request Example

Request Example

✅ Success Response

Transaction Status Notifications

Callback Parameters

Sample Callback Data

Transaction History

Parameters

Code Examples

Request Example

✅ Success Response

❌ Error Response

Card Collection (Visa / Mastercard)

1. Initiate a card collection