mobiska-sdk 0.1.0

A Django-based SDK for integrating with the Mobiska Payment Gateway

Mobiska Payment Gateway SDK

A Django-based SDK for integrating with the Mobiska Payment Gateway.

Features

• Make payment requests to the Mobiska API
• Send SMS messages through the Mobiska API
• Check SMS account balance
• Track and manage payment transactions and SMS messages
• RESTful API endpoints for client applications
• Admin interface for monitoring transactions and SMS messages

Installation

1. Clone the repository:

git clone https://github.com/kofnet002/mobiska-sdk.git
cd mobiska-sdk

2. Create a virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure your Mobiska API credentials in core/settings.py:

# Mobiska API Settings
MOBISKA_API_URL = 'https://mobiska-api.stimuluzdev.com'
MOBISKA_API_USERNAME = 'client_key'  # Replace with actual client key
MOBISKA_API_PASSWORD = 'secret_key'  # Replace with actual secret key

4. Run migrations:

python manage.py migrate

5. Create a superuser to access the admin interface:

python manage.py createsuperuser

6. Run the development server:

python manage.py runserver

Usage

Direct SDK Usage

Payment Processing

from apps.mobiska.client import MobiskaClient

# Initialize the client
client = MobiskaClient(
    username="YOUR_USERNAME",  # Optional, defaults to settings.MOBISKA_API_USERNAME
    password="YOUR_PASSWORD",  # Optional, defaults to settings.MOBISKA_API_PASSWORD
)

# Make a payment request
response = client.make_payment(
    service_id=2,
    reference="Payment for Product XYZ",
    nickname="MyStore",
    transaction_id="unique-transaction-id-123",
    customer_number="0541840988",
    network="MTN",  # MTN, VOD, AIR, VIS, MAS
    amount=100.00,
    payment_option="MOM",  # MOM, CRD, CRM
    callback_url="https://mywebsite.com/payment-callback",
    currency_code="GHS"
)

# Handle the response
if response["response_code"] == "202":
    print("Payment request successful:", response["response_message"])
else:
    print("Payment request failed:", response["response_message"])

SMS Messaging

from apps.mobiska.client import MobiskaClient

# Initialize the client
client = MobiskaClient()

# Send an SMS message
response = client.send_sms(
    service_id=2,
    unique_id="unique-sms-id-123",
    sender_id="MYCOMPANY",
    msg_body="Your verification code is 123456",
    recipient_number=["233541234567", "233241234567"]
)

# Handle the response
if response["response_code"] == "000":
    print("SMS sent successfully:", response["response_message"])
    print("Message ID:", response["response_data"]["message_id"])
else:
    print("SMS sending failed:", response["response_message"])

# Check SMS account balance
balance_response = client.check_sms_account_balance(service_id=2)
if balance_response["response_code"] == "000":
    print(f"Account balance: {balance_response['response_data']['balance']} {balance_response['response_data']['currency']}")
else:
    print("Failed to retrieve balance:", balance_response["response_message"])

API Usage

Payment API

Make a POST request to /api/payment/make/ with the following payload:

{
  "service_id": 2,
  "reference": "Payment for Product XYZ",
  "nickname": "MyStore",
  "transaction_id": "unique-transaction-id-123",
  "trans_type": "CTM",
  "customer_number": "0541840988",
  "nw": "MTN",
  "amount": 100.00,
  "payment_option": "MOM",
  "callback_url": "https://mywebsite.com/payment-callback",
  "currency_code": "GHS",
  "currency_val": 1,
  "request_time": "2025-07-25T02:30:00Z"
}

Authentication

The API uses token authentication. To obtain a token:

curl -X POST http://localhost:8000/api-token-auth/ -d "client_key=yourclientkey&secret_key=yoursecretkey"

Then include the token in your API requests:

curl -X POST http://localhost:8000/api/payment/make/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 2, ...}'

SMS API

Sending SMS

Make a POST request to /api/v1/sms/send/ with the following payload:

{
  "service_id": 2,
  "unique_id": "unique-sms-id-123",
  "sender_id": "MYCOMPANY",
  "msg_body": "Your verification code is 123456",
  "recipient_number": ["233541234567", "233241234567"]
}

Example using curl:

curl -X POST http://localhost:8000/api/v1/sms/send/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 2, "unique_id": "unique-sms-id-123", "sender_id": "MYCOMPANY", "msg_body": "Your verification code is 123456", "recipient_number": ["233541234567", "233241234567"]}'

Checking SMS Account Balance

Make a GET request to /api/v1/sms/balance/ to check your SMS account balance.

curl -X GET http://localhost:8000/api/v1/sms/balance/ \
  -H "Authorization: Token YOUR_TOKEN"

Admin Interface

Access the admin interface at http://localhost:8000/admin/ to view and manage payment transactions and SMS messages.

Payment Transactions

The admin interface allows you to monitor all payment transactions, including their status, response codes, and other details.

SMS Messages

The SMS Messages section in the admin interface provides tracking and monitoring of all SMS messages sent through the Mobiska API. You can view:

• Message content and recipients
• Delivery status and response codes
• Timestamps for message creation and sending
• Full API response data

Network Providers

• MTN: MTN Mobile Money
• VOD: Vodafone Cash
• AIR: AirtelTigo Money
• VIS: Visa Card
• MAS: Mastercard

Payment Options

• MOM: Mobile Money
• CRD: Bank Cards
• CRM: Hosted Checkout (Mobile Money and Cards)

API Credentials

To generate your API credentials, follow these steps:

1. Combine your client key and secret key: {client_key}:{secret_key}
2. Base64 encode the combined string
3. Create the Authorization header: Authorization: Basic {base64_encoded_string}

Example:

echo -n "mob_client_123:sk_live_abcdef123456" | base64

License

MIT License